@api-client/core 0.5.8 → 0.5.11

package/src/models/RequestAuthorization.ts

@@ -101,9 +101,10 @@ export class RequestAuthorization {
   }
 
   toJSON(): IRequestAuthorization {
+    const { config={} } = this;
     const result:IRequestAuthorization = {
       kind: Kind,
-      config: this.config || {},
+      config: { ...config },
       enabled: this.enabled || false,
       type: this.type || '' as AuthorizationType,
       valid: this.valid || true,

package/src/models/Server.ts

@@ -1,3 +1,6 @@
+import { IProperty, Property } from './Property.js';
+import { UriTemplate } from '../lib/parsers/UriTemplate.js';
+
 export const Kind = 'Core#Server';
 
 export interface IServer {
@@ -129,8 +132,10 @@ export class Server {
 
   /**
    * Constructs the final URI from the server configuration.
+   * 
+   * @param variables When set it evaluates the generated URI against these variables
    */
-  readUri(): string {
+  readUri(variables?: (IProperty | Property)[]): string {
     const { uri, protocol, basePath } = this;
     let result = '';
     if (!uri) {
@@ -148,6 +153,32 @@ export class Server {
       }
       result += basePath.startsWith('/') ? basePath : `/${basePath}`
     }
+    if (variables) {
+      return this.evaluateUri(result, variables);
+    }
+    return result;
+  }
+
+  /**
+   * Evaluates the URI against the variables.
+   * 
+   * Note, this doesn't throw errors. When error occurs it returns the input string. 
+   * 
+   * @param uri The URI to process
+   * @param variables The list of variables to use
+   * @returns Expanded URI.
+   */
+  protected evaluateUri(uri: string, variables: (IProperty | Property)[]): string {
+    if (!variables || !variables.length) {
+      return uri;
+    }
+    let result = uri;
+    try {
+      const map = Property.toMap(variables);
+      result = new UriTemplate(uri).expand(map, { ignoreMissing: true });
+    } catch (e) {
+      // 
+    }
     return result;
   }
 }

package/src/models/store/Capabilities.ts

@@ -46,7 +46,7 @@ export interface ICapabilities {
    */
   canAddChildren: boolean;
   /**
-   * Whether the user can delete the file.
+   * 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.

package/src/models/store/File.ts

@@ -1,4 +1,4 @@
-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';
@@ -64,6 +64,11 @@ export interface IStoredFile {
    * 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;
 }
 
 /**
@@ -83,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
@@ -96,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).
@@ -103,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) {
@@ -143,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 {
@@ -167,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;
   }
@@ -195,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,
@@ -242,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 {
   /**
@@ -64,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.
@@ -141,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 = {
@@ -159,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 = {
@@ -176,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 = {
@@ -267,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/runtime/actions/runnable/DeleteCookieRunnable.ts

@@ -2,7 +2,7 @@ import { IHttpRequest } from 'src/models/HttpRequest.js';
 import { ActionRunnable } from './ActionRunnable.js';
 import { IDeleteCookieAction } from '../../../models/actions/runnable/DeleteCookieAction.js';
 import { Events } from '../../../events/Events.js';
-import { IRequestLog } from 'src/models/RequestLog.js';
+import { IRequestLog } from '../../../models/RequestLog.js';
 
 export class DeleteCookieRunnable extends ActionRunnable {
   async response(log: IRequestLog): Promise<void> {

package/src/runtime/actions/runnable/SetCookieRunnable.ts

@@ -4,7 +4,7 @@ import { ActionRunnable } from './ActionRunnable.js';
 import { ISetCookieAction } from '../../../models/actions/runnable/SetCookieAction.js';
 import { Events } from '../../../events/Events.js';
 import { RequestDataExtractor } from '../../../data/RequestDataExtractor.js';
-import { IRequestLog } from 'src/models/RequestLog.js';
+import { IRequestLog } from '../../../models/RequestLog.js';
 
 export class SetCookieRunnable extends ActionRunnable {
   async request(request: IHttpRequest): Promise<void> {

package/src/runtime/actions/runnable/SetVariableRunnable.ts

@@ -3,7 +3,7 @@ import { ActionRunnable } from './ActionRunnable.js';
 import { ISetVariableAction } from '../../../models/actions/runnable/SetVariableAction.js';
 import { Events } from '../../../events/Events.js';
 import { RequestDataExtractor } from '../../../data/RequestDataExtractor.js';
-import { IRequestLog } from 'src/models/RequestLog.js';
+import { IRequestLog } from '../../../models/RequestLog.js';
 
 export class SetVariableRunnable extends ActionRunnable {
   async request(request: IHttpRequest): Promise<void> {

package/src/runtime/http-engine/CoreEngine.ts

@@ -3,7 +3,7 @@ import tls from 'tls';
 import http from 'http';
 import https from 'https';
 import { HttpEngine, HttpEngineOptions, HeadersReceivedDetail } from './HttpEngine.js';
-import { IRequestLog } from 'src/models/RequestLog.js';
+import { IRequestLog } from '../../models/RequestLog.js';
 import { IHttpRequest } from '../../models/HttpRequest.js';
 import { Response } from '../../models/Response.js';
 import { SerializableError } from '../../models/SerializableError.js';

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.
    * 
@@ -300,4 +338,20 @@ export class FilesSdk extends SdkBase {
     const url = this.sdk.getUrl(RouteBuilder.files());
     return this.sdk.ws.createAndConnect(url.toString(), token);
   }
+
+  /**
+   * Creates a WS client that listens to the file events.
+   * 
+   * @param key The file key to observe
+   * @param media Whether to observe changes to the file media instead of meta.
+   * @param request Optional request options.
+   */
+  async observeFile(key: string, media?: boolean, request: ISdkRequestOptions = {}): Promise<WebSocketNode | WebSocket> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.file(key));
+    if (media) {
+      url.searchParams.set('alt', 'media');
+    }
+    return this.sdk.ws.createAndConnect(url.toString(), token);
+  }
 }

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.
    */