@api-client/core 0.8.21 → 0.9.0

package/src/runtime/store/SpacesSdk.ts

@@ -0,0 +1,136 @@
+import { SdkBase, E_RESPONSE_STATUS, E_RESPONSE_NO_VALUE, E_INVALID_JSON, E_RESPONSE_UNKNOWN, ISdkRequestOptions } from './SdkBase.js';
+import { RouteBuilder } from './RouteBuilder.js';
+import { ContextChangeRecord, ContextListOptions, ContextListResult } from '../../events/BaseEvents.js';
+import { ISpace, Kind as SpaceKind } from '../../models/Space.js';
+import { SdkError } from './Errors.js';
+
+export class SpacesSdk extends SdkBase {
+  /**
+   * Lists spaces created by the user.
+   * @param options The list query options
+   */
+  async list(options?: ContextListOptions, request: ISdkRequestOptions = {}): Promise<ContextListResult<ISpace>> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.spaces());
+    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);
+      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: ContextListResult<ISpace>;
+    try {
+      data = JSON.parse(result.body);
+    } catch (e) {
+      throw new Error(`${E_PREFIX}${E_INVALID_JSON}.`);
+    }
+    if (!Array.isArray(data.items)) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_UNKNOWN}.`);
+    }
+    return data;
+  }
+
+  /**
+   * Creates a space from a space definition.
+   * 
+   * @param space The space definition.
+   */
+  async add(space: ISpace, request: ISdkRequestOptions = {}): Promise<ContextChangeRecord<ISpace>> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.spaces());
+    const body = JSON.stringify(space);
+    const result = await this.sdk.http.post(url.toString(), { token, body });
+    this.inspectCommonStatusCodes(result.status);
+    const E_PREFIX = 'Unable to create a space. ';
+    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: ContextChangeRecord<ISpace>;
+    try {
+      data = JSON.parse(result.body);
+    } catch (e) {
+      throw new Error(`${E_PREFIX}${E_INVALID_JSON}.`);
+    }
+    if (!data.key) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_UNKNOWN}.`);
+    }
+    return data;
+  }
+
+  /**
+   * Reads a single space from the store.
+   * @param key The key of the space to read.
+   */
+  async read(key: string, request: ISdkRequestOptions = {}): Promise<ISpace> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.space(key));
+    const result = await this.sdk.http.get(url.toString(), { token });
+    this.inspectCommonStatusCodes(result.status);
+    const E_PREFIX = 'Unable to read a space. ';
+    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: ISpace;
+    try {
+      data = JSON.parse(result.body);
+    } catch (e) {
+      throw new Error(`${E_PREFIX}${E_INVALID_JSON}.`);
+    }
+    if (data.kind !== SpaceKind) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_UNKNOWN}.`);
+    }
+    return data;
+  }
+
+  /**
+   * Marks space as deleted.
+   * Note, this does not remove any data from the store. It marks the space as deleted
+   * and then the space is ignored by most of the API.
+   * 
+   * @param key The key of the space to delete.
+   */
+  async delete(key: string, request: ISdkRequestOptions = {}): Promise<void> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.space(key));
+    const result = await this.sdk.http.delete(url.toString(), { token });
+    this.inspectCommonStatusCodes(result.status, result.body);
+    const E_PREFIX = 'Unable to delete the space. ';
+    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;
+    }
+  }
+}

package/src/runtime/store/TrashSdk.ts

@@ -0,0 +1,159 @@
+import { SdkBase, E_RESPONSE_STATUS, E_RESPONSE_NO_VALUE, E_INVALID_JSON, E_RESPONSE_UNKNOWN, ISdkRequestOptions } from './SdkBase.js';
+import { RouteBuilder } from './RouteBuilder.js';
+import { ContextChangeRecord, ContextListResult, ContextSpaceListOptions } from '../../events/BaseEvents.js';
+import { SdkError } from './Errors.js';
+import { IFile } from '../../models/store/File.js';
+import { TrashEntry, TrashEntryCreate } from '../../models/TrashEntry.js';
+
+export class TrashSdk extends SdkBase {
+  /**
+   * Inserts a record of file delete.
+   * 
+   * @param entry The trash entry definition
+   * @param space The parent space of the file
+   */
+  async add(entry: TrashEntryCreate, space: string, request: ISdkRequestOptions = {}): Promise<ContextChangeRecord<TrashEntry>> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.trash());
+    url.searchParams.set('space', space);
+    const body = JSON.stringify(entry);
+    const result = await this.sdk.http.post(url.toString(), { token, body });
+    this.inspectCommonStatusCodes(result.status);
+    const E_PREFIX = 'Unable to create a trash. ';
+    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: ContextChangeRecord<TrashEntry>;
+    try {
+      data = JSON.parse(result.body);
+    } catch (e) {
+      throw new Error(`${E_PREFIX}${E_INVALID_JSON}.`);
+    }
+    if (!data.key) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_UNKNOWN}.`);
+    }
+    return data;
+  }
+
+  /**
+   * Lists trashed entires.
+   * @param options The list query options.
+   */
+  async list(options: ContextSpaceListOptions, request: ISdkRequestOptions = {}): Promise<ContextListResult<TrashEntry>> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.trash());
+    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 trash. ';
+    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: ContextListResult<TrashEntry>;
+    try {
+      data = JSON.parse(result.body);
+    } catch (e) {
+      throw new Error(`${E_PREFIX}${E_INVALID_JSON}.`);
+    }
+    if (!Array.isArray(data.items)) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_UNKNOWN}.`);
+    }
+    return data;
+  }
+
+  /**
+   * Removes a trash entry permanently from the store.
+   * @param key The key of the deleted object
+   */
+  async delete(key: string, request: ISdkRequestOptions = {}): Promise<void> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.trashItem(key));
+    const result = await this.sdk.http.delete(url.toString(), { token });
+    this.inspectCommonStatusCodes(result.status, result.body);
+    const E_PREFIX = 'Unable to delete the trash entry. ';
+    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;
+    }
+  }
+
+  /**
+   * Restores a file from the trash.
+   * It deletes a trash entry and updates the `file` object.
+   * 
+   * @param key The key of the file to restore
+   */
+  async restore(key: string, request: ISdkRequestOptions = {}): Promise<ContextChangeRecord<IFile>> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.trashRestore(key));
+    const result = await this.sdk.http.put(url.toString(), { token });
+    this.inspectCommonStatusCodes(result.status, result.body);
+    const E_PREFIX = 'Unable to restore from trash. ';
+    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;
+    }
+    if (!result.body) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`);
+    }
+    let data: ContextChangeRecord<IFile>;
+    try {
+      data = JSON.parse(result.body);
+    } catch (e) {
+      throw new Error(`${E_PREFIX}${E_INVALID_JSON}.`);
+    }
+    if (!data.key) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_UNKNOWN}.`);
+    }
+    return data;
+  }
+
+  /**
+   * Empties the trash for the given space.
+   * @param space The space key to remove trash for.
+   */
+  async empty(space: string, request: ISdkRequestOptions = {}): Promise<void> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.trashEmpty(space));
+    const result = await this.sdk.http.delete(url.toString(), { token });
+    this.inspectCommonStatusCodes(result.status, result.body);
+    const E_PREFIX = 'Unable to empty trash. ';
+    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;
+    }
+  }
+}

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, ISdkRequestOptions } from './SdkBase.js';
 import { RouteBuilder } from './RouteBuilder.js';
-import { IListOptions, IListResponse } from '../../models/store/Backend.js';
 import { IUser } from '../../models/store/User.js';
+import { ContextListResult, ContextListOptions } from '../../events/BaseEvents.js';
 
 export class UsersSdk extends SdkBase {
   /**
@@ -39,7 +39,7 @@ export class UsersSdk extends SdkBase {
    * @param options Optional query options.
    * @param request Optional request options.
    */
-  async list(options?: IListOptions, request: ISdkRequestOptions = {}): Promise<IListResponse<IUser>> {
+  async list(options?: ContextListOptions, request: ISdkRequestOptions = {}): Promise<ContextListResult<IUser>> {
     const token = request.token || this.sdk.token;
     const url = this.sdk.getUrl(RouteBuilder.users());
     this.sdk.appendListOptions(url, options);
@@ -53,7 +53,7 @@ export class UsersSdk extends SdkBase {
     if (!result.body) {
       throw new Error(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`);
     }
-    let data: IListResponse<IUser>;
+    let data: ContextListResult<IUser>;
     try {
       data = JSON.parse(result.body);
     } catch (e) {

package/src/runtime/store/interfaces/ApiClientStore.ts

@@ -0,0 +1,39 @@
+import { Certificates } from "./Certificates.js";
+import { Files } from "./Files.js";
+import { History } from "./History.js";
+import { Media } from "./Media.js";
+import { Revisions } from "./Revisions.js";
+import { Spaces } from "./Spaces.js";
+import { Trash } from "./Trash.js";
+
+/**
+ * A base class to define access to the API Client store.
+ * This is used by particular store implementation (like IDB or net-store).
+ */
+export interface ApiClientStore {
+  /**
+   * The current space.
+   * The bindings will fill up workspace key information when needed. 
+   * This way the events won't need to contain this information.
+   */
+  space?: string;
+
+  /**
+   * Initializes the store.
+   */
+  initializeStore(): Promise<void>;
+
+  history: History;
+
+  spaces: Spaces; 
+
+  certificates: Certificates; 
+
+  trash: Trash; 
+  
+  revisions: Revisions; 
+
+  media: Media; 
+
+  files: Files;
+}

package/src/runtime/store/interfaces/Certificates.ts

@@ -0,0 +1,56 @@
+import { HttpCertificate } from "../../../models/ClientCertificate.js";
+import { ContextChangeRecord, ContextDeleteRecord, ContextListResult, ContextSpaceListOptions, IBulkOperationResult } from "../../../events/BaseEvents.js";
+
+/**
+ * A store for the client certificates.
+ * This just keeps record of removed files. File location does not change.
+ */
+export interface Certificates {
+  /**
+   * Inserts a certificate to the store
+   * 
+   * @param value The value to insert.
+   * @param space The parent space of the certificate.
+   */
+  add(value: HttpCertificate, space: string): Promise<ContextChangeRecord<HttpCertificate>>;
+
+  /**
+   * Adds certificates in a bulk operation.
+   * @param value The lits of certificates to add.
+   * @param space The parent workspace
+   * @returns The list of inserted certificates. `undefined` when there was an error inserting a certificate.
+   */
+  addBulk(values: HttpCertificate[], space: string): Promise<IBulkOperationResult<ContextChangeRecord<HttpCertificate>>>;
+
+  /**
+   * @param key The key of the certificate to read.
+   */
+  read(key: string): Promise<HttpCertificate>;
+
+  /**
+   * Lists certificate entires.
+   * 
+   * @param space The parent space of the certificate.
+   * @param options The list query options.
+   */
+  list(options?: ContextSpaceListOptions): Promise<ContextListResult<HttpCertificate>>;
+
+  /**
+   * Marks the certificate as deleted.
+   * 
+   * @param key The key of the certificate to delete.
+   */
+  delete(key: string): Promise<ContextDeleteRecord>;
+
+  /**
+   * Removed certificates in a bulk operation.
+   * @param keys The list of certificate keys to delete.
+   */
+  deleteBulk(keys: string[]): Promise<IBulkOperationResult<ContextDeleteRecord>>;
+
+  /**
+   * Removes all certificates from the store for the given workspace.
+   * @param space The parent workspace key
+   */
+  empty(space: string): Promise<void>;
+}

package/src/runtime/store/interfaces/Files.ts

@@ -0,0 +1,70 @@
+import { IFile, FileAddOptions, FileBreadcrumb } from '../../../models/store/File.js';
+import { ContextChangeRecord, ContextDeleteRecord, ContextListResult, ContextSpaceListOptions, IBulkOperationResult, IPatchInfo, IPatchRevision } from '../../../events/BaseEvents.js';
+
+/**
+ * A store that stores file/folder metadata in a filesystem like structure.
+ * 
+ * In API Client the `space` is a parent for all data kept in the application.
+ */
+export interface Files {
+  /**
+   * Lists files in a space.
+   * @param options Query options. It must include `space`.
+   * @param kinds Optionally, lists the files with the listed kinds.
+   */
+  list(options: ContextSpaceListOptions, kinds?: string[]): Promise<ContextListResult<IFile>>;
+
+  /**
+   * Adds a new file to the store. Note, this throws an error when a file already exists.
+   * 
+   * @param input The file to add.
+   * @param space The id of the parent space.
+   * @param opts The file add options.
+   */
+  add(input: IFile, space: string, opts?: FileAddOptions): Promise<ContextChangeRecord<IFile>>;
+
+  /**
+   * Reads a file meta from the store.
+   * It throws when the file does not exist or was deleted.
+   * 
+   * @param key The id of the file to read the metadata for.
+   */
+  read(key: string): Promise<IFile>;
+
+  /**
+   * Reads multiple files in a single call.
+   * Unlike the `read()` method, this does not throw when a file is not found or deleted.
+   * When the file is missing it inserts `undefined` or `null` in the resulting array at the index
+   * of the missing key.
+   * 
+   * Note, this returns `undefined` when directly querying the store but it may return `null` when 
+   * structured clone algorithm is used between the application and the database.
+   * 
+   * @param keys The list of keys to read
+   */
+  readBulk(keys: string[]): Promise<IBulkOperationResult<IFile>>;
+
+  /**
+   * Marks file as deleted.
+   * Files are not deleted by using this method. They are marked as deleted and later ignored 
+   * by most of the API.
+   * 
+   * @param key The database id of the file to remove.
+   */
+  delete(key: string): Promise<ContextDeleteRecord>;
+
+  /**
+   * This is the preferred way to update a file metadata. It allows to apply a reversible patch 
+   * to the file and reverse it on demand.
+   * 
+   * @param key The datastore id of the file to patch
+   * @param info The patch to apply.
+   */
+  patch(key: string, info: IPatchInfo): Promise<IPatchRevision>;
+
+  /**
+   * Lists breadcrumbs to the file.
+   * @param key The lowest file in the hierarchy
+   */
+  breadcrumbs(key: string): Promise<ContextListResult<FileBreadcrumb>>;
+}

package/src/runtime/store/interfaces/History.ts

@@ -0,0 +1,64 @@
+import { ContextChangeRecord, ContextDeleteRecord, ContextListResult, HistoryListOptions, IBulkOperationResult } from "../../../events/BaseEvents.js";
+import { IHttpHistory, IHttpHistoryBulkAdd } from "../../../models/HttpHistory.js";
+
+/**
+ * A store for the HTTP requests history.
+ */
+export interface History {
+  /**
+   * Adds a history object to the store.
+   * 
+   * @param history The history object
+   * @param space The parent space key
+   */
+  add(item: IHttpHistory): Promise<ContextChangeRecord<IHttpHistory>>;
+  /**
+   * Adds history in a bulk operation.
+   * @param info The bulk add operation schema.
+   * @param space The parent space key
+   */
+  addBulk(info: IHttpHistoryBulkAdd): Promise<IBulkOperationResult<ContextChangeRecord<IHttpHistory>>>;
+  /**
+   * Lists the history data.
+   * @param space The parent space key
+   * @param options List options
+   */
+  list(options?: HistoryListOptions): Promise<ContextListResult<IHttpHistory>>;
+  /**
+   * Marks the data as deleted. It also removes the data from the indexes.
+   * Only the owner can delete the history object. This may change in the future.
+   * 
+   * @param key The history object key to delete. This is an URL-encoded key.
+   */
+  delete(key: string): Promise<ContextDeleteRecord>;
+  /**
+   * Deletes a history in a bulk operation.
+   * @param keys The list of history keys to delete. This is base64url encoded keys
+   */
+  deleteBulk(keys: string[]): Promise<IBulkOperationResult<ContextDeleteRecord>>;
+  /**
+   * Reads a history item.
+   * 
+   * @param key The key of the history object to read.
+   */
+  read(key: string): Promise<IHttpHistory>;
+  /**
+   * Clears the datastore from history for a space.
+   * 
+   * @param space The parent space key
+   */
+  clearSpace(space: string): Promise<void>;
+  /**
+   * Clears all history from a project
+   * 
+   * @param project The parent project key
+   */
+  clearProject(project: string): Promise<void>;
+  /**
+   * Clears all history from a request
+   * 
+   * @param project The parent project key
+   * @param request The parent request key
+   */
+  clearRequest(project: string, request: string): Promise<void>;
+}

package/src/runtime/store/interfaces/Media.ts

@@ -0,0 +1,46 @@
+import { IPatchInfo, IPatchRevision } from "../../../events/BaseEvents.js";
+import { MediaReadOptions } from "../../../models/store/File.js";
+
+/**
+ * A media is the contents of a File.
+ * Keys are the same as for a file but kept in a different namespace.
+ * 
+ * Note, this class does not check for space dependency. This should be done when requesting a file, not contents.
+ */
+export interface Media {
+  /**
+   * Creates / re-creates file contents.
+   * 
+   * @param key The datastore id of the file to create/update the contents for.
+   * @param contents The contents to store.
+   * @param mime The content mime type. Used for (de)serialization.
+   * @param allowOverwrite Whether overwriting is permitted. When not then in throws an error when trying to re-create a file.
+   */
+  add(key: string, contents: unknown, mime: string, allowOverwrite: boolean): Promise<void>;
+
+  /**
+   * Reads file contents.
+   * @param key The datastore key of the file
+   * @param opts Read options.
+   */
+  read(key: string, opts?: MediaReadOptions): Promise<unknown>;
+
+  /**
+   * Deletes file contents.
+   * Note, this won't broadcast the delete event as this is done by the `files?alt=meta`.
+   * 
+   * @param key The file key to delete.
+   */
+  delete(key: string): Promise<void>;
+
+  /**
+   * This is the preferred way to update a file contents.
+   * 
+   * Note, the broadcast event will most likely contain the `kind` of the **file** metadata and not content's.
+   * The media has no concept of a `kind` as it may store any data.
+   * 
+   * @param key The datastore key of the file to patch
+   * @param info The patch to apply.
+   */
+  patch(key: string, info: IPatchInfo): Promise<IPatchRevision>;
+}

package/src/runtime/store/interfaces/Revisions.ts

@@ -0,0 +1,27 @@
+import { IRevision } from "../../../models/store/Revision.js";
+import { ContextListResult, ContextSpaceListOptions } from "../../../events/BaseEvents.js";
+import { JsonPatch } from "@api-client/json";
+
+/**
+ * A store to keep revision data for a file.
+ * This only stores revision data for file contents, not metadata.
+ */
+export interface Revisions {
+  /**
+   * Lists revisions for a single file.
+   * 
+   * @param key The id of the file to lists revisions for.
+   * @param options The list query options
+   */
+  list(key: string, options: ContextSpaceListOptions): Promise<ContextListResult<IRevision>>;
+
+  /**
+   * Creates a new revision for a file contents.
+   * 
+   * @param key The datastore id of the file
+   * @param space The parent space
+   * @param kind The kind of the file that was patched
+   * @param patch The applied patch.
+   */
+  add(key: string, space: string, kind: string, patch: JsonPatch): Promise<IRevision>;
+}

package/src/runtime/store/interfaces/Spaces.ts

@@ -0,0 +1,48 @@
+import { ISpace } from "../../../models/Space.js";
+import { ContextListResult, ContextListOptions, ContextDeleteRecord, ContextChangeRecord } from "../../../events/BaseEvents.js";
+
+/**
+ * A store that keeps a list of spaces created in the application.
+ */
+export interface Spaces {
+  /**
+   * Lists spaces created by the user.
+   * @param options The list query options
+   */
+  list(options?: ContextListOptions): Promise<ContextListResult<ISpace>>;
+
+  /**
+   * Creates a space from the name.
+   * 
+   * @param name The name of the space to create
+   */
+  add(name: string): Promise<ContextChangeRecord<ISpace>>;
+
+  /**
+   * Creates a space from a space definition.
+   * @param space The space definition.
+   */
+  add(space: ISpace): Promise<ContextChangeRecord<ISpace>>;
+
+  /**
+   * Creates a space from a name or a definition.
+   * 
+   * @param nameOrObject The space name or definition.
+   */
+  add(nameOrObject: string | ISpace): Promise<ContextChangeRecord<ISpace>>;
+
+  /**
+   * Reads a single space from the store.
+   * @param key The key of the space to read.
+   */
+  read(key: string): Promise<ISpace>;
+
+  /**
+   * Marks space as deleted.
+   * Note, this does not remove any data from the store. It marks the space as deleted
+   * and then the space is ignored by most of the API.
+   * 
+   * @param key The key of the space to delete.
+   */
+  delete(key: string): Promise<ContextDeleteRecord>;
+}