@api-client/core 0.4.0 → 0.4.1

package/src/runtime/store/ProjectsSdk.ts

@@ -0,0 +1,147 @@
+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 { HttpProject, IHttpProject, Kind as HttpProjectKind } from '../../models/HttpProject.js';
+
+export class ProjectsSdk extends SdkBase {
+  /**
+   * Creates a project in a user space.
+   * 
+   * @param space The user space key
+   * @param project THe project to create
+   * @returns The key of the created project.
+   */
+  async create(space: string, project: IHttpProject | HttpProject): Promise<string> {
+    const { token } = this.sdk;
+    const url = this.sdk.getUrl(RouteBuilder.spaceProjects(space));
+    const body = JSON.stringify(project);
+    const result = await this.sdk.http.post(url.toString(), { token, body });
+    this.inspectCommonStatusCodes(result.status);
+    const E_PREFIX = 'Unable to create a project. ';
+    if (result.status !== 204) {
+      this.logInvalidResponse(result);
+      throw new Error(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`);
+    }
+    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 a project definition from the store.
+   * @param space The user space key
+   * @param project The project key
+   * @returns The definition of the project.
+   */
+  async read(space: string, project: string): Promise<IHttpProject> {
+    const { token } = this.sdk;
+    const url = this.sdk.getUrl(RouteBuilder.spaceProject(space, project));
+    const result = await this.sdk.http.get(url.toString(), { token });
+    this.inspectCommonStatusCodes(result.status);
+    const E_PREFIX = 'Unable to read a project. ';
+    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: IHttpProject;
+    try {
+      data = JSON.parse(result.body);
+    } catch (e) {
+      throw new Error(`${E_PREFIX}${E_INVALID_JSON}.`);
+    }
+    if (data.kind !== HttpProjectKind) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_UNKNOWN}.`);
+    }
+    return data;
+  }
+
+  /**
+   * Lists projects in the space
+   * 
+   * @param space The user space key
+   * @param options Optional query options.
+   */
+  async list(space: string, options?: IListOptions): Promise<IListResponse> {
+    const { token } = this.sdk;
+    const url = this.sdk.getUrl(RouteBuilder.spaceProjects(space));
+    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 projects. ';
+    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;
+  }
+
+  /**
+   * Deletes a project form the store.
+   * 
+   * @param space The key of the parent space.
+   * @param project The key of the project to delete.
+   */
+  async delete(space: string, project: string): Promise<void> {
+    const { token } = this.sdk;
+    const url = this.sdk.getUrl(RouteBuilder.spaceProject(space, project));
+    const result = await this.sdk.http.delete(url.toString(), { token });
+    this.inspectCommonStatusCodes(result.status);
+    const E_PREFIX = 'Unable to delete a project. ';
+    if (result.status !== 204) {
+      this.logInvalidResponse(result);
+      throw new Error(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`);
+    }
+  }
+
+  /**
+   * Patches a project in the store.
+   * @param space The key of the parent user space
+   * @param project The key of project to patch.
+   * @param value The JSON patch to be processed.
+   * @returns The JSON patch to revert the change using the `json8-patch` library
+   */
+  async patch(space: string, project: string, value: JsonPatch): Promise<JsonPatch> {
+    const { token } = this.sdk;
+    const url = this.sdk.getUrl(RouteBuilder.spaceProject(space, project));
+    const body = JSON.stringify(value);
+    const result = await this.sdk.http.patch(url.toString(), { token, body });
+    this.inspectCommonStatusCodes(result.status);
+    const E_PREFIX = 'Unable to patch a project. ';
+    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: 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;
+  }
+}

package/src/runtime/store/RouteBuilder.ts

@@ -0,0 +1,89 @@
+/**
+ * A helper class to make sure routes user and reported by this service are consistent.
+ */
+export class RouteBuilder {
+  /**
+   * @returns The path to the /spaces route.
+   */
+  static spaces(): string {
+    return '/spaces';
+  }
+
+  /**
+   * @returns The path to the /spaces/[id] route.
+   */
+  static space(key: string): string {
+    return `/spaces/${key}`;
+  }
+
+  /**
+   * @returns The path to the /spaces/[id]/users route.
+   */
+  static spaceUsers(key: string): string {
+    return `/spaces/${key}/users`;
+  }
+
+  /**
+   * @returns The path to the /spaces/[id]/projects route.
+   */
+  static spaceProjects(key: string): string {
+    return `/spaces/${key}/projects`;
+  }
+
+  /**
+   * @returns The path to the /spaces/[id]/projects/[id] route.
+   */
+  static spaceProject(space: string, project: string): string {
+    return `/spaces/${space}/projects/${project}`;
+  }
+
+  /**
+   * @returns The path to the /spaces/[id]/projects/[id]/revisions route.
+   */
+  static projectRevisions(space: string, project: string): string {
+    return `/spaces/${space}/projects/${project}/revisions`;
+  }
+
+  /**
+   * @returns The path to the /backend route.
+   */
+  static backend(): string {
+    return '/store';
+  }
+
+  static sessions(): string {
+    return '/sessions'
+  }
+
+  static sessionRenew(): string {
+    return '/sessions/renew'
+  }
+
+  static usersMe(): string {
+    return '/users/me'
+  }
+
+  static users(): string {
+    return '/users'
+  }
+
+  static user(key: string): string {
+    return `/users/${key}`
+  }
+
+  static history(): string {
+    return `/history`;
+  }
+
+  static historyBatchCreate(): string {
+    return `/history/batch/create`;
+  }
+
+  static historyBatchDelete(): string {
+    return `/history/batch/delete`;
+  }
+
+  static historyItem(key: string): string {
+    return `/history/${key}`;
+  }
+}

package/src/runtime/store/Sdk.ts

@@ -0,0 +1,131 @@
+import { IListOptions } from '../../models/Backend.js';
+import { Http } from './Http.js';
+import { WsClient } from './WsClient.js';
+import { AuthSdk } from './AuthSdk.js';
+import { BackendSdk } from './BackendSdk.js';
+import { SpacesSdk } from './SpacesSdk.js';
+import { ProjectsSdk } from './ProjectsSdk.js';
+import { UsersSdk } from './UsersSdk.js';
+import { HistorySdk } from './HistorySdk.js';
+
+const baseUriSymbol = Symbol('baseUri');
+
+/**
+ * NodeJS API for API Client's net-store module.
+ */
+export abstract class Sdk {
+  /**
+   * The token to use with requests. Can be overwritten with each API call.
+   */
+  token?: string;
+  /**
+   * The user authentication features.
+   */
+  auth = new AuthSdk(this);
+  /**
+   * The store information features
+   */
+  store = new BackendSdk(this);
+  /**
+   * The user spaces features.
+   */
+  space = new SpacesSdk(this);
+  /**
+   * The user projects features.
+   */
+  project = new ProjectsSdk(this);
+  /**
+   * Reads user information.
+   */
+  user = new UsersSdk(this);
+  /**
+   * The HTTP(S) requests.
+   */
+  abstract http: Http;
+  /**
+   * The web socket requests.
+   */
+  abstract ws: WsClient;
+  /**
+   * The history data.
+   */
+  history = new HistorySdk(this);
+
+
+  [baseUriSymbol] = '';
+
+  /**
+   * @returns The base URI to the store.
+   */
+  get baseUri(): string {
+    return this[baseUriSymbol];
+  }
+
+  /**
+   * @param value The base URI to the store.
+   */
+  set baseUri(value: string) {
+    if (!value) {
+      throw new Error(`Invalid value for the baseUri`);
+    }
+    let url: URL;
+    try {
+      url = new URL(value);
+    } catch (e) {
+      throw new Error(`Invalid baseUri: Not an URL`);
+    }
+    this[baseUriSymbol] = url.origin;
+    const { pathname } = url;
+    if (pathname && pathname !== '/') {
+      this.basePath = pathname;
+    } else {
+      this.basePath = undefined;
+    }
+  }
+
+  /**
+   * @param baseUri The base URI to the store.
+   * @param basePath The base path (the router prefix) for the server.
+   */
+  constructor(baseUri: string, public basePath?: string) {
+    this.baseUri = baseUri;
+  }
+
+  /**
+   * Creates a full URL for a path.
+   * This adds the server's base path and the passed path to the configured base URL.
+   * @param path The path to the endpoint, without the base path.
+   */
+  getUrl(path='/'): URL {
+    const { baseUri, basePath='' } = this;
+    let userPath = path;
+    if (basePath && userPath.startsWith(basePath)) {
+      userPath = userPath.substring(basePath.length);
+    }
+    return new URL(`${basePath}${userPath}`, baseUri);
+  }
+
+  /**
+   * Appends list options to the query parameters.
+   * @param url The URL object to the API endpoint
+   * @param options The list options, if any
+   */
+  appendListOptions(url: URL, options: IListOptions = {}): void {
+    const { searchParams } = url;
+    if (options.cursor) {
+      searchParams.set('cursor', options.cursor);
+    } else {
+      if (typeof options.limit === 'number') {
+        searchParams.set('limit', String(options.limit));
+      }
+      if (options.query) {
+        searchParams.set('query', options.query);
+      }
+      if (Array.isArray(options.queryField)) {
+        options.queryField.forEach((field) => {
+          searchParams.append('queryField', field);
+        });
+      }
+    }
+  }
+}

package/src/runtime/store/SdkBase.ts

@@ -0,0 +1,72 @@
+import { Headers } from '../../lib/headers/Headers.js';
+import { Sdk } from './Sdk.js';
+
+export interface IStoreRequestOptions {
+  method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+  headers?: Record<string, string>,
+  body?: string | Buffer;
+  /**
+   * Adds the token to the headers.
+   */
+  token?: string;
+}
+
+export interface IStoreResponse {
+  status: number;
+  headers: Headers;
+  body?: string;
+}
+
+export interface IStoreTokenInfo {
+  /**
+   * The token to use.
+   */
+  token: string;
+  /**
+   * The timestamp when the token expires.
+   * Note, clients may have a different date than the store.
+   * 
+   * May not be set when the token does not expire.
+   */
+  expires?: number;
+}
+
+export const E_INVALID_JSON = 'The response is not a valid JSON.';
+export const E_RESPONSE_NO_VALUE = 'The response has no value.';
+export const E_RESPONSE_STATUS = 'Invalid response status: ';
+export const E_RESPONSE_UNKNOWN = 'The response has unknown format.';
+export const E_RESPONSE_LOCATION = 'The response has no "location" header.';
+
+
+export class SdkBase {
+  constructor(public sdk: Sdk) {}
+
+  protected logInvalidResponse(response: IStoreResponse): void {
+    if (response.body) {
+      try {
+        const data = JSON.parse(response.body);
+        if (data.message) {
+          console.warn(`[Store message]: ${data.message}`);
+        }
+      } catch (e) {
+        // .
+      }
+    }
+  }
+
+  /**
+   * Throws unified message for a common error status codes.
+   * It handles 404, 403, and 401 status codes.
+   */
+  protected inspectCommonStatusCodes(status: number): void {
+    if (status === 404) {
+      throw new Error(`Not found.`);
+    }
+    if (status === 403) {
+      throw new Error(`You have no access to this resource.`);
+    }
+    if (status === 401) {
+      throw new Error(`Not authorized.`);
+    }
+  }
+}

package/src/runtime/store/SpacesSdk.ts

@@ -0,0 +1,190 @@
+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';
+
+export class SpacesSdk extends SdkBase {
+  /**
+   * Lists spaces in the store.
+   * @param options Optional query options.
+   */
+  async list(options?: IListOptions): Promise<IListResponse> {
+    const { token } = this.sdk;
+    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);
+      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;
+  }
+
+  /**
+   * Creates a workspace in the store.
+   * @param space The workspace definition.
+   * @returns The key of the creates space.
+   */
+  async create(space: IWorkspace | Workspace): Promise<string> {
+    const { token } = this.sdk;
+    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 user space. ';
+    if (result.status !== 204) {
+      this.logInvalidResponse(result);
+      throw new Error(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`);
+    }
+    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 a user space definition from the store.
+   * @param key The user space key
+   * @returns The definition of the user space.
+   */
+  async read(key: string): Promise<IUserWorkspace> {
+    const { token } = this.sdk;
+    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 user space. ';
+    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: IUserWorkspace;
+    try {
+      data = JSON.parse(result.body);
+    } catch (e) {
+      throw new Error(`${E_PREFIX}${E_INVALID_JSON}.`);
+    }
+    if (data.kind !== WorkspaceKind) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_UNKNOWN}.`);
+    }
+    return data;
+  }
+
+  /**
+   * Patches a user space in the store.
+   * @param key The key of the user space to patch
+   * @param value The JSON patch to be processed.
+   * @returns The JSON patch to revert the change using the `json8-patch` library
+   */
+  async patch(key: string, value: JsonPatch): Promise<JsonPatch> {
+    const { token } = this.sdk;
+    const url = this.sdk.getUrl(RouteBuilder.space(key));
+    const body = JSON.stringify(value);
+    const result = await this.sdk.http.patch(url.toString(), { token, body });
+    this.inspectCommonStatusCodes(result.status);
+    const E_PREFIX = 'Unable to patch a user space. ';
+    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: 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 space in the store.
+   * 
+   * @param key The key of the space to delete.
+   */
+  async delete(key: string): Promise<void> {
+    const { token } = this.sdk;
+    const url = this.sdk.getUrl(RouteBuilder.space(key));
+    const result = await this.sdk.http.delete(url.toString(), { token });
+    this.inspectCommonStatusCodes(result.status);
+    const E_PREFIX = 'Unable to delete a user space. ';
+    if (result.status !== 204) {
+      this.logInvalidResponse(result);
+      throw new Error(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`);
+    }
+  }
+
+  /**
+   * Updates the sharing options of the space.
+   * 
+   * @param key The user space key
+   * @param value The patch operation on the space's ACL
+   */
+  async patchUsers(key: string, value: UserAccessOperation[]): Promise<void> {
+    const { token } = this.sdk;
+    const url = this.sdk.getUrl(RouteBuilder.spaceUsers(key));
+    const body = JSON.stringify(value);
+    const result = await this.sdk.http.patch(url.toString(), { token, body });
+    this.inspectCommonStatusCodes(result.status);
+    const E_PREFIX = 'Unable to patch a user space. ';
+    if (result.status !== 204) {
+      this.logInvalidResponse(result);
+      throw new Error(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`);
+    }
+  }
+
+  /**
+   * Lists uses having access to the user space.
+   * 
+   * @param key The user space key
+   */
+  async listUsers(key: string): Promise<IListResponse> {
+    const { token } = this.sdk;
+    const url = this.sdk.getUrl(RouteBuilder.spaceUsers(key));
+    const result = await this.sdk.http.get(url.toString(), { token });
+    this.inspectCommonStatusCodes(result.status);
+    const E_PREFIX = 'Unable to list users in the space. ';
+    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/StoreSdkNode.ts

@@ -0,0 +1,13 @@
+import { HttpNode } from './HttpNode.js';
+import { WsClientNode } from './WsClientNode.js';
+import { Sdk } from './Sdk.js';
+import { Http } from './Http.js';
+import { WsClient } from './WsClient.js';
+
+/**
+ * NodeJS API for API Client's net-store module.
+ */
+export class StoreSdk extends Sdk {
+  http: Http = new HttpNode(this);
+  ws: WsClient = new WsClientNode(this);
+}

package/src/runtime/store/StoreSdkWeb.ts

@@ -0,0 +1,13 @@
+import { HttpWeb } from './HttpWeb.js';
+import { WsClientWeb } from './WsClientWeb.js';
+import { Sdk } from './Sdk.js';
+import { Http } from './Http.js';
+import { WsClient } from './WsClient.js';
+
+/**
+ * NodeJS API for API Client's net-store module.
+ */
+export class StoreSdk extends Sdk {
+  http: Http = new HttpWeb(this);
+  ws: WsClient = new WsClientWeb(this);
+}