@api-client/core 0.4.2 → 0.5.0

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;
+}

package/src/runtime/store/SpacesSdk.ts

@@ -2,8 +2,8 @@ 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';
 
 export class SpacesSdk extends SdkBase {
   /**
@@ -65,7 +65,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 +78,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 +145,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);

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"}

package/src/models/User.ts

@@ -1,138 +0,0 @@
-export type AccessControlLevel = 'read' | 'comment' | 'write' | 'admin' | 'owner';
-
-/**
- * This is used in the communication with the backend to add/change user's access to the resource.
- */
-export interface IUserAccessOperation {
-  /**
-   * The user id.
-   */
-  uid: string;
-}
-
-export interface IUserAccessAddOperation extends IUserAccessOperation {
-  op: "add";
-  /**
-   * The level that the user has access to.
-   */
-  value: AccessControlLevel;
-}
-
-export interface IUserAccessRemoveOperation extends IUserAccessOperation {
-  op: "remove";
-}
-
-export type UserAccessOperation = IUserAccessAddOperation | IUserAccessRemoveOperation;
-
-/**
- * The definition of an access control.
- * The user may have access to a workspace so this is the object describing the level of the workspace.
- */
-export interface IAccessControl {
-  /**
-   * The data store key of the referenced object the user has access to.
-   */
-  key: string;
-  /**
-   * The level that the user has access to.
-   */
-  level: AccessControlLevel;
-}
-
-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;
-}
-
-/**
- * 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;
-}
-
-/**
- * This object may be created for each user in the system.
- * It describes to which spaces user has access to.
- */
-export interface IUserSpaces {
-  /**
-   * The list of access to the spaces for the user.
-   */
-  spaces: IAccessControl[];
-  /**
-   * The data store key of the user that has access to the space.
-   * This is also the key of the entry.
-   */
-  user: string;
-}
-
-/**
- * An abstract user object that contains access information to a space.
- */
-export interface ISpaceUser extends BaseUser {
-  /**
-   * The level that the user has access to.
-   */
-  level: AccessControlLevel;
-}