@api-client/core 0.4.4 → 0.5.2

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,332 @@
+import v4 from '../../lib/uuid.js';
+
+export const Kind = 'Core#Permission';
+
+export type PermissionType = 'user' | 'group' | 'anyone';
+export type PermissionRole = 'owner' | 'reader' | 'commenter' | 'writer';
+
+interface IBasePermission {
+  /**
+   * 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;
+}
+
+/**
+ * A schema describing a permission to a store object.
+ */
+export interface IPermission extends IBasePermission{
+  kind: typeof Kind;
+  /**
+   * The data store key of the permission.
+   * This property is generated by the store and is not writable.
+   */
+  key: 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);
+  }
+
+  /**
+   * Creates a permission object from other than key and kind values.
+   */
+  static fromValues(init: IBasePermission): Permission {
+    return new Permission({
+      ...init,
+      key: v4(),
+      kind: Kind,
+    });
+  }
+
+  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;
+}

package/src/runtime/store/RouteBuilder.ts

@@ -86,4 +86,8 @@ export class RouteBuilder {
   static historyItem(key: string): string {
     return `/history/${key}`;
   }
+
+  static sharedSpaces(): string {
+    return '/shared/spaces';
+  }
 }

package/src/runtime/store/Sdk.ts

@@ -7,6 +7,7 @@ import { SpacesSdk } from './SpacesSdk.js';
 import { ProjectsSdk } from './ProjectsSdk.js';
 import { UsersSdk } from './UsersSdk.js';
 import { HistorySdk } from './HistorySdk.js';
+import { SharedSdk } from './SharedSdk.js';
 
 const baseUriSymbol = Symbol('baseUri');
 
@@ -50,6 +51,10 @@ export abstract class Sdk {
    * The history data.
    */
   history = new HistorySdk(this);
+  /**
+   * The shared data.
+   */
+  shared = new SharedSdk(this);
 
 
   [baseUriSymbol] = '';
@@ -126,6 +131,9 @@ export abstract class Sdk {
           searchParams.append('queryField', field);
         });
       }
+      if (options.parent) {
+        searchParams.set('parent', options.parent);
+      }
     }
   }
 }

package/src/runtime/store/SharedSdk.ts

@@ -0,0 +1,35 @@
+import { SdkBase, E_RESPONSE_STATUS, E_RESPONSE_NO_VALUE, E_INVALID_JSON, E_RESPONSE_UNKNOWN } from './SdkBase.js';
+import { RouteBuilder } from './RouteBuilder.js';
+import { IListOptions, IListResponse } from '../../models/Backend.js';
+
+export class SharedSdk extends SdkBase {
+  /**
+   * Lists shared with the user spaces.
+   * @param options Optional query options.
+   */
+  async list(options?: IListOptions): Promise<IListResponse> {
+    const { token } = this.sdk;
+    const url = this.sdk.getUrl(RouteBuilder.sharedSpaces());
+    this.sdk.appendListOptions(url, options);
+    const result = await this.sdk.http.get(url.toString(), { token });
+    this.inspectCommonStatusCodes(result.status);
+    const E_PREFIX = 'Unable to list spaces. ';
+    if (result.status !== 200) {
+      this.logInvalidResponse(result);
+      throw new Error(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`);
+    }
+    if (!result.body) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`);
+    }
+    let data: IListResponse;
+    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;
+  }
+}

package/src/runtime/store/SpacesSdk.ts

@@ -2,8 +2,17 @@ import { JsonPatch } from 'json8-patch';
 import { SdkBase, E_RESPONSE_STATUS, E_RESPONSE_NO_VALUE, E_INVALID_JSON, E_RESPONSE_UNKNOWN, E_RESPONSE_LOCATION } from './SdkBase.js';
 import { RouteBuilder } from './RouteBuilder.js';
 import { IListOptions, IListResponse } from '../../models/Backend.js';
-import { IWorkspace, IUserWorkspace, Workspace, Kind as WorkspaceKind } from '../../models/Workspace.js';
-import { UserAccessOperation } from '../../models/User.js';
+import { IWorkspace, Workspace, Kind as WorkspaceKind } from '../../models/Workspace.js';
+import { AccessOperation } from '../../models/store/Permission.js';
+import WebSocketNode from 'ws';
+
+export interface ISpaceCreateOptions {
+  /**
+   * Optional parent space id.
+   * When set it creates a space under this parent.
+   */
+  parent?: string;
+}
 
 export class SpacesSdk extends SdkBase {
   /**
@@ -41,9 +50,10 @@ export class SpacesSdk extends SdkBase {
    * @param space The workspace definition.
    * @returns The key of the creates space.
    */
-  async create(space: IWorkspace | Workspace): Promise<string> {
+  async create(space: IWorkspace | Workspace, opts: ISpaceCreateOptions = {}): Promise<string> {
     const { token } = this.sdk;
-    const url = this.sdk.getUrl(RouteBuilder.spaces());
+    const path = opts.parent ? RouteBuilder.space(opts.parent) : RouteBuilder.spaces();
+    const url = this.sdk.getUrl(path);
     const body = JSON.stringify(space);
     const result = await this.sdk.http.post(url.toString(), { token, body });
     this.inspectCommonStatusCodes(result.status);
@@ -65,7 +75,7 @@ export class SpacesSdk extends SdkBase {
    * @param key The user space key
    * @returns The definition of the user space.
    */
-  async read(key: string): Promise<IUserWorkspace> {
+  async read(key: string): Promise<IWorkspace> {
     const { token } = this.sdk;
     const url = this.sdk.getUrl(RouteBuilder.space(key));
     const result = await this.sdk.http.get(url.toString(), { token });
@@ -78,7 +88,7 @@ export class SpacesSdk extends SdkBase {
     if (!result.body) {
       throw new Error(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`);
     }
-    let data: IUserWorkspace;
+    let data: IWorkspace;
     try {
       data = JSON.parse(result.body);
     } catch (e) {
@@ -145,7 +155,7 @@ export class SpacesSdk extends SdkBase {
    * @param key The user space key
    * @param value The patch operation on the space's ACL
    */
-  async patchUsers(key: string, value: UserAccessOperation[]): Promise<void> {
+  async patchUsers(key: string, value: AccessOperation[]): Promise<void> {
     const { token } = this.sdk;
     const url = this.sdk.getUrl(RouteBuilder.spaceUsers(key));
     const body = JSON.stringify(value);
@@ -187,4 +197,13 @@ export class SpacesSdk extends SdkBase {
     }
     return data;
   }
+
+  /**
+   * Creates a WS client that listens to the spaces events.
+   */
+  async observeSpaces(): Promise<WebSocketNode | WebSocket> {
+    const { token } = this.sdk;
+    const url = this.sdk.getUrl(RouteBuilder.spaces());
+    return this.sdk.ws.createAndConnect(url.toString(), token);
+  }
 }

package/src/runtime/store/StoreSdkNode.ts

@@ -4,6 +4,9 @@ import { Sdk } from './Sdk.js';
 import { Http } from './Http.js';
 import { WsClient } from './WsClient.js';
 
+export { IStoreTokenInfo, IStoreResponse, IStoreRequestOptions } from './SdkBase.js';
+export { ISpaceCreateOptions } from './SpacesSdk.js';
+
 /**
  * NodeJS API for API Client's net-store module.
  */

package/src/runtime/store/StoreSdkWeb.ts

@@ -4,6 +4,9 @@ import { Sdk } from './Sdk.js';
 import { Http } from './Http.js';
 import { WsClient } from './WsClient.js';
 
+export { IStoreTokenInfo, IStoreResponse, IStoreRequestOptions } from './SdkBase.js';
+export { ISpaceCreateOptions } from './SpacesSdk.js';
+
 /**
  * NodeJS API for API Client's net-store module.
  */

package/src/runtime/store/UsersSdk.ts

@@ -1,7 +1,7 @@
 import { SdkBase, E_RESPONSE_STATUS, E_RESPONSE_NO_VALUE, E_INVALID_JSON, E_RESPONSE_UNKNOWN } from './SdkBase.js';
 import { RouteBuilder } from './RouteBuilder.js';
 import { IListOptions, IListResponse } from '../../models/Backend.js';
-import { IUser } from '../../models/User.js';
+import { IUser } from '../../models/store/User.js';
 
 export class UsersSdk extends SdkBase {
   async me(): Promise<IUser> {

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

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