@api-client/core 0.5.2 → 0.5.5

package/src/models/store/File.ts

@@ -1,8 +1,25 @@
 import { IPermission } 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';
 
 export const DefaultOwner = 'default';
 
 export interface IStoredFile {
+  /**
+   * The kind of the File
+   */
+  kind: string;
+  /**
+   * The identifier of the entity
+   */
+  key: string;
+  /**
+   * The projects's meta info.
+   */
+  info: IThing;
   /**
    * 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).
@@ -23,17 +40,22 @@ export interface IStoredFile {
    */
   deleted?: boolean;
   /**
-   * The timestamp of when the file was deleted.
-   */
-  deletedTime?: number;
-  /**
-   * The id of the user that has deleted the file.
+   * The information about the delete information.
+   * Always set when the `delete` is true.
    */
-  deletingUser?: string;
+  deletedInfo?: IDeletion;
   /**
    * The owner of this object. The id of the User object.
    */
   owner: string;
+  /**
+   * The last modification made to this file.
+   */
+  lastModified: IModification;
+  /**
+   * An arbitrary list of labels applied to the file.
+   */
+  labels?: string[];
 }
 
 /**
@@ -54,6 +76,18 @@ export interface IFile extends IStoredFile {
 }
 
 export class StoredFile {
+  /**
+   * The kind of the File
+   */
+  kind = '';
+  /**
+   * The identifier of the entity
+   */
+  key = '';
+  /**
+   * The name of the environment.
+   */
+  info: Thing = Thing.fromName('');
   /**
    * 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).
@@ -74,54 +108,140 @@ export class StoredFile {
    */
   deleted?: boolean;
   /**
-   * The timestamp of when the file was deleted.
+   * The information about the delete information.
+   * Always set when the `delete` is true.
    */
-  deletedTime?: number;
-  /**
-   * The id of the user that has deleted the file.
-   */
-  deletingUser?: string;
+  deletedInfo?: IDeletion;
   /**
    * 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 = '';
+  owner = DefaultOwner;
+  /**
+   * The last modification made to this file.
+   */
+  lastModified: IModification = { user: '', time: 0, byMe: false };
+  /**
+   * An arbitrary list of labels applied to the file.
+   */
+  labels?: string[];
 
   new(init: IStoredFile): void {
-    const { parents=[], permissionIds=[], deleted, deletedTime, deletingUser, owner = DefaultOwner } = init;
+    const { key = v4(), info, kind, parents=[], permissionIds=[], deleted, deletedInfo, owner = DefaultOwner, lastModified, labels } = init;
+    this.key = key;
+    this.kind = kind;
+    if (info) {
+      this.info = new Thing(info);
+    } else {
+      this.info = Thing.fromName('');
+    }
     this.parents = parents;
     this.permissionIds = permissionIds;
     this.owner = owner;
+    this.lastModified = lastModified ? { ...lastModified } : { user: '', time: 0, byMe: false };
     if (typeof deleted === 'boolean') {
       this.deleted = deleted;
-      this.deletedTime = deletedTime;
-      this.deletingUser = deletingUser;
+      this.deletedInfo = deletedInfo ? { ...deletedInfo } : undefined;
     } else {
       this.deleted = undefined;
-      this.deletedTime = undefined;
-      this.deletingUser = undefined;
+      this.deletedInfo = undefined;
+    }
+    if (Array.isArray(labels)) {
+      this.labels = labels;
+    } else {
+      this.labels = undefined; 
     }
   }
 
   toJSON(): IStoredFile {
     const { owner = DefaultOwner } = this;
     const result: IStoredFile = {
+      key: this.key,
+      kind: this.kind,
+      info: this.info.toJSON(),
       parents: this.parents,
       permissionIds: this.permissionIds,
+      lastModified: this.lastModified,
       owner,
     };
-    if (typeof this.deleted === 'boolean') {
+    if (this.deleted) {
       result.deleted = this.deleted;
-
-      if (this.deletedTime) {
-        result.deletedTime = this.deletedTime;
-      }
-      if (this.deletingUser) {
-        result.deletingUser = this.deletingUser;
-      }
+      result.deletedInfo = this.deletedInfo;
+    }
+    if (Array.isArray(this.labels)) {
+      result.labels = this.labels;
     }
     return result;
   }
+
+  /**
+   * Updates the "lastModified" value.
+   * A helper method for a common task.
+   * 
+   * @param user The user that modifies the entity.
+   */
+  setLastModified(user: IUser): void {
+    if (!user) {
+      throw new Error(`The user is required.`);
+    }
+    if (user.kind !== UserKind) {
+      throw new Error(`Invalid value for the user when setting "lastModified".`);
+    }
+    this.lastModified = {
+      byMe: false,
+      time: Date.now(),
+      user: user.key,
+      name: user.name,
+    };
+  }
+
+  /**
+   * Adds a label to the list of labels.
+   * 
+   * It makes sure the value is a valid, non-empty string and the `labels` array is set.
+   * 
+   * It does nothing when the label already exists.
+   * 
+   * @param label The label to set.
+   */
+  addLabel(label: string): void {
+    if (typeof label !== 'string') {
+      throw new Error(`The label must be a string.`);
+    }
+    if (!label.trim()) {
+      throw new Error(`The label is required.`);
+    }
+    if (!Array.isArray(this.labels)) {
+      this.labels = [];
+    }
+    if (this.labels.includes(label)) {
+      return;
+    }
+    this.labels.push(label);
+  }
+
+  /**
+   * Marks the entity as deleted.
+   * 
+   * A helper method for a common task.
+   * 
+   * @param user The user that deletes the entity.
+   */
+  setDeleted(user: IUser): void {
+    if (!user) {
+      throw new Error(`The user is required.`);
+    }
+    if (user.kind !== UserKind) {
+      throw new Error(`Invalid value for the user when setting "lastModified".`);
+    }
+    this.deleted = true;
+    this.deletedInfo = {
+      byMe: false,
+      time: Date.now(),
+      user: user.key,
+      name: user.name,
+    };
+  }
 }
 
 export class File extends StoredFile {

package/src/models/store/Modification.ts

@@ -0,0 +1,24 @@
+/**
+ * Information about a modification of a File.
+ */
+export interface IModification {
+  /**
+   * The key of the user modifying the record.
+   */
+  user: string;
+  /**
+   * User name modifying the record. May not be set when there's no actual user.
+   */
+  name?: string;
+  /**
+   * Whether the modification was performed by the requesting the data user.
+   * 
+   * Note for store implementers, this field should not be stored and populated every time the 
+   * record is requested.
+   */
+  byMe: boolean;
+  /**
+   * A timestamp when the object was modified.
+   */
+  time: number;
+}

package/src/runtime/store/Errors.ts

@@ -0,0 +1,100 @@
+import { SerializableError, ISerializedError } from '../../models/SerializableError.js';
+
+export interface IApiError {
+  /**
+   * Indicates the response is an error.
+   */
+  error: boolean;
+  /**
+   * The same as the status code but returned with the body.
+   */
+  code: number;
+  /**
+   * The human-readable error message
+   */
+  message: string;
+  /**
+   * The detailed message about the error, if any.
+   */
+  detail?: string;
+}
+
+export class ApiError {
+  get name(): string {
+    return 'ApiError';
+  }
+
+  code: number;
+  message: string;
+  detail?: string;
+
+  constructor(message: string, code: number);
+  constructor(init: IApiError);
+
+  constructor(messageOrInit: string | IApiError, code?: number) {
+    if (typeof messageOrInit === 'string') {
+      if (typeof code === 'number') {
+        this.code = code;
+      } else {
+        this.code = 0;
+      }
+      this.message = messageOrInit;
+    } else {
+      this.message = messageOrInit.message;
+      this.code = messageOrInit.code;
+      if (messageOrInit.detail) {
+        this.detail = messageOrInit.detail;
+      }
+    }
+  }
+
+  toJSON(): IApiError {
+    const { message, code, detail } = this;
+    const result: IApiError = {
+      error: true,
+      message,
+      code,
+    };
+    if (detail) {
+      result.detail = detail;
+    }
+    return result;
+  }
+
+  toString(): string {
+    return this.message;
+  }
+}
+
+export interface ISdkError extends ISerializedError {
+  /**
+   * The raw response from the server.
+   */
+  response?: string;
+  /**
+   * Optional detailed message returned by the server.
+   */
+  detail?: string;
+}
+
+export class SdkError extends SerializableError {
+  /**
+   * The raw response from the server.
+   */
+  response?: string;
+  /**
+   * Optional detailed message returned by the server.
+   */
+  detail?: string;
+
+  toJSON(): ISdkError {
+    const result = super.toJSON();
+    if (this.response) {
+      result.response = this.response;
+    }
+    if (this.detail) {
+      result.detail = this.detail;
+    }
+    return result;
+  }
+}

package/src/runtime/store/FilesSdk.ts

@@ -0,0 +1,302 @@
+import WebSocketNode from 'ws';
+import { JsonPatch } from 'json8-patch';
+import { SdkBase, E_RESPONSE_STATUS, E_RESPONSE_NO_VALUE, E_INVALID_JSON, E_RESPONSE_UNKNOWN, E_RESPONSE_LOCATION, ISdkRequestOptions } from './SdkBase.js';
+import { RouteBuilder } from './RouteBuilder.js';
+import { IListOptions, IListResponse } from '../../models/Backend.js';
+import { AccessOperation } from '../../models/store/Permission.js';
+import { IUser } from '../../models/store/User.js';
+import { IFile } from '../../models/store/File.js';
+import { Kind as ProjectKind } from '../../models/Project.js';
+import { Kind as WorkspaceKind } from '../../models/Workspace.js';
+import { IHttpProject } from '../../models/HttpProject.js';
+import { SdkError } from './Errors.js';
+
+export interface IFileCreateOptions {
+  /**
+   * Optional parent file id.
+   * When set it creates a file under this parent.
+   */
+  parent?: string;
+}
+
+export class FilesSdk extends SdkBase {
+  /**
+   * Lists files (spaces, projects, etc) in the store.
+   * 
+   * @param kinds the list of kinds to list. Spaces are always included.
+   * @param options Optional query options.
+   * @param request Optional request options.
+   */
+  async list(kinds: (typeof ProjectKind | typeof WorkspaceKind)[], options?: IListOptions, request: ISdkRequestOptions = {}): Promise<IListResponse<IFile>> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.files());
+    this.sdk.appendListOptions(url, options);
+    kinds.forEach(k => url.searchParams.append('kind', k));
+    const result = await this.sdk.http.get(url.toString(), { token });
+    this.inspectCommonStatusCodes(result.status, result.body);
+    const E_PREFIX = 'Unable to list files. ';
+    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>;
+    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;
+  }
+
+  /**
+   * Creates a file in the store.
+   * 
+   * @param file The definition of a file that extends the IFile interface or one of the supported by the server schemas.
+   * @param request Optional request options.
+   * @returns The key of the creates file.
+   */
+  async create(file: IFile | IHttpProject, opts: IFileCreateOptions = {}, request: ISdkRequestOptions = {}): Promise<string> {
+    const token = request.token || this.sdk.token;
+    const path = opts.parent ? RouteBuilder.file(opts.parent) : RouteBuilder.files();
+    const url = this.sdk.getUrl(path);
+    const body = JSON.stringify(file);
+    const result = await this.sdk.http.post(url.toString(), { token, body });
+    this.inspectCommonStatusCodes(result.status, result.body);
+    const E_PREFIX = 'Unable to create a file. ';
+    if (result.status !== 204) {
+      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;
+    }
+    const location = result.headers.get('location');
+    if (!location) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_LOCATION}`);
+    }
+    const id = location.split('/').pop();
+    return id as string;
+  }
+
+  /**
+   * Reads file metadata from the store.
+   * 
+   * @param key The file key
+   * @param request Optional request options.
+   * @returns THe file metadata
+   */
+  read(key: string, media: false, request?: ISdkRequestOptions): Promise<IFile>;
+  /**
+   * Reads file contents from the store.
+   * 
+   * @param key The file key
+   * @param request Optional request options.
+   * @returns THe file contents
+   */
+  read(key: string, media: true, request?: ISdkRequestOptions): Promise<unknown>;
+
+  /**
+   * Reads a user file definition from the store.
+   * @param key The file key
+   * @param media When true it reads file contents rather than metadata.
+   * @param request Optional request options.
+   */
+  async read(key: string, media?: boolean, request: ISdkRequestOptions = {}): Promise<IFile | unknown> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.file(key));
+    if (media) {
+      url.searchParams.set('alt', 'media');
+    }
+    const result = await this.sdk.http.get(url.toString(), { token });
+    this.inspectCommonStatusCodes(result.status, result.body);
+    const E_PREFIX = 'Unable to read a file. ';
+    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: IFile;
+    try {
+      data = JSON.parse(result.body);
+    } catch (e) {
+      throw new Error(`${E_PREFIX}${E_INVALID_JSON}.`);
+    }
+    if (!data.kind) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_UNKNOWN}.`);
+    }
+    return data;
+  }
+
+  /**
+   * Patches file's meta in the store.
+   * 
+   * @param key The file key
+   * @param value The patch to apply.
+   * @param request Optional request options.
+   */
+  patch(key: string, value: JsonPatch, media: false, request?: ISdkRequestOptions): Promise<JsonPatch>;
+
+  /**
+   * Patches file's content in the store.
+   * 
+   * @param key The file key
+   * @param value The patch to apply.
+   * @param request Optional request options.
+   */
+  patch(key: string, value: JsonPatch, media: true, request?: ISdkRequestOptions): Promise<JsonPatch>;
+
+  /**
+   * Patches a file in the store.
+   * @param key The key of the file to patch
+   * @param value The JSON patch to be processed.
+   * @param request Optional request options.
+   * @returns The JSON patch to revert the change using the `json8-patch` library
+   */
+  async patch(key: string, value: JsonPatch, media?: boolean, request: ISdkRequestOptions = {}): Promise<JsonPatch> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.file(key));
+    if (media) {
+      url.searchParams.set('alt', 'media');
+    }
+    const body = JSON.stringify(value);
+    const result = await this.sdk.http.patch(url.toString(), { token, body });
+    this.inspectCommonStatusCodes(result.status, result.body);
+    const E_PREFIX = 'Unable to patch a file. ';
+    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: any;
+    try {
+      data = JSON.parse(result.body);
+    } catch (e) {
+      throw new Error(`${E_PREFIX}${E_INVALID_JSON}.`);
+    }
+    if (!data.revert) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_UNKNOWN}.`);
+    }
+    return data.revert as JsonPatch;
+  }
+
+  /**
+   * Deletes the file in the store.
+   * 
+   * @param key The key of the file to delete.
+   * @param request Optional request options.
+   */
+  async delete(key: string, request: ISdkRequestOptions = {}): Promise<void> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.file(key));
+    const result = await this.sdk.http.delete(url.toString(), { token });
+    this.inspectCommonStatusCodes(result.status, result.body);
+    const E_PREFIX = 'Unable to delete a file. ';
+    if (result.status !== 204) {
+      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;
+    }
+  }
+
+  /**
+   * Updates the sharing options of the file.
+   * 
+   * @param key The file key
+   * @param value The patch operation on the file's ACL
+   * @param request Optional request options.
+   */
+  async patchUsers(key: string, value: AccessOperation[], request: ISdkRequestOptions = {}): Promise<void> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.fileUsers(key));
+    const body = JSON.stringify(value);
+    const result = await this.sdk.http.patch(url.toString(), { token, body });
+    this.inspectCommonStatusCodes(result.status, result.body);
+    const E_PREFIX = 'Unable to patch a file. ';
+    if (result.status !== 204) {
+      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;
+    }
+  }
+
+  /**
+   * Lists uses having access to the file.
+   * 
+   * @param key The file key
+   * @param request Optional request options.
+   */
+  async listUsers(key: string, request: ISdkRequestOptions = {}): Promise<IListResponse<IUser>> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.fileUsers(key));
+    const result = await this.sdk.http.get(url.toString(), { token });
+    this.inspectCommonStatusCodes(result.status, result.body);
+    const E_PREFIX = 'Unable to list users in the file. ';
+    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<IUser>;
+    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;
+  }
+
+  /**
+   * Creates a WS client that listens to the files events.
+   * @param request Optional request options.
+   */
+  async observeFiles(request: ISdkRequestOptions = {}): Promise<WebSocketNode | WebSocket> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.files());
+    return this.sdk.ws.createAndConnect(url.toString(), token);
+  }
+}