@api-client/core 0.3.1 → 0.3.4

package/src/models/SentRequest.ts

@@ -0,0 +1,125 @@
+import { IHttpRequest, HttpRequest, Kind, IBaseHttpRequest } from './HttpRequest.js';
+import { TransportRequest as LegacyTransportRequest } from './legacy/request/ArcRequest.js';
+import { PayloadSerializer } from '../lib/transformers/PayloadSerializer.js';
+
+export interface IBaseSentRequest extends IBaseHttpRequest {
+  /**
+   * The HTTP message sent to the server (full message).
+   * Some HTTP clients may not give this information.
+   */
+  httpMessage?: string;
+  /**
+   * The timestamp when the request was started (before the connection is made)
+   */
+  startTime: number;
+  /**
+   * The timestamp of when the response ended.
+   * This is always set when the response is ready. May not be set when the request is ongoing.
+   */
+  endTime?: number;
+}
+
+/**
+ * An interface describing a request made by the HTTP transport.
+ * Each transport used by ARC must return this structure in the response event.
+ * This is not a replacement for the editor request that also has to be returned.
+ * 
+ * Another difference is that this headers contains a final list of headers sent to the 
+ * server, including default headers, content-length, authorization, and so on.
+ */
+export interface ISentRequest extends IHttpRequest, IBaseSentRequest {
+}
+
+/**
+ * A class that describes a request that has been sent by the transport library
+ * to the remote machine. It contains the base HTTP request properties plus
+ * the sent message and start and end time.
+ */
+export class SentRequest extends HttpRequest {
+  /**
+   * The HTTP message sent to the server (full message).
+   * Some HTTP clients may not give this information.
+   */
+  httpMessage?: string;
+  /**
+   * The timestamp when the request was started (before the connection is made)
+   */
+  startTime = 0;
+  /**
+   * The timestamp of when the response ended.
+   * When `0` then the requests is still being transported.
+   */
+  endTime = 0;
+
+  static fromBaseValues(values: IBaseSentRequest): SentRequest {
+    return new SentRequest({
+      ...values,
+      kind: Kind,
+    });
+  }
+
+  static async fromLegacy(input: LegacyTransportRequest): Promise<SentRequest> {
+    const init: ISentRequest = {
+      kind: Kind,
+      url: input.url || '',
+      startTime: input.startTime || 0,
+    };
+    if (typeof input.endTime === 'number') {
+      init.endTime = input.endTime;
+    }
+    if (input.headers) {
+      init.headers = input.headers;
+    }
+    if (input.httpMessage) {
+      init.httpMessage = input.httpMessage;
+    }
+    if (input.method) {
+      init.method = input.method;
+    }
+    if (input.payload) {
+      init.payload = await PayloadSerializer.serialize(input.payload);
+    }
+    return new SentRequest(init);
+  }
+
+  /**
+   * @param input The request definition used to restore the state.
+   */
+  constructor(input?: string|ISentRequest) {
+    super(input);
+    let init: ISentRequest;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      init = {
+        kind: Kind,
+        url: '',
+        startTime: 0,
+      };
+    }
+    this.new(init);
+  }
+
+  /**
+   * Creates a new request clearing anything that is so far defined.
+   * 
+   * Note, this throws an error when the object is not an ARC request.
+   */
+  new(init: ISentRequest): void {
+    super.new(init);
+    const { httpMessage, startTime=0, endTime=0 } = init;
+    this.httpMessage = httpMessage;
+    this.startTime = startTime;
+    this.endTime = endTime;
+  }
+
+  toJSON(): ISentRequest {
+    const request = super.toJSON() as ISentRequest;
+    request.httpMessage = this.httpMessage;
+    request.startTime = this.startTime;
+    request.endTime = this.endTime;
+    return request;
+  }
+}

package/src/models/SerializablePayload.ts

@@ -0,0 +1,68 @@
+import { PayloadSerializer, Payload, DeserializedPayload, hasBuffer } from '../lib/transformers/PayloadSerializer.js';
+
+export class SerializablePayload {
+  /**
+   * The serialized payload message.
+   */
+  payload?: Payload;
+  /**
+   * The payload in its original format.
+   * May not be populated when the `getPayload()` was not yet read.
+   */
+  protected _sourcePayload: unknown;
+
+  /**
+   * Sets the payload on the request.
+   * This transforms the source `message` to its serialized form using the `PayloadSerializer`.
+   */
+  async writePayload(message: unknown): Promise<void> {
+    this._sourcePayload = message;
+    if (typeof message === 'string') {
+      this.payload = message;
+    } else {
+      this.payload = await PayloadSerializer.serialize(message as DeserializedPayload);
+    }
+  }
+
+  /**
+   * Reads the payload as its original format.
+   * It uses the `PayloadSerializer` to process the data.
+   */
+  async readPayload(): Promise<DeserializedPayload> {
+    if (!this._sourcePayload) {
+      this._sourcePayload = await PayloadSerializer.deserialize(this.payload);
+    }
+    return this._sourcePayload as DeserializedPayload;
+  }
+
+  /**
+   * Reads the payload as string, when it is possible.
+   * This method assumes that the payload is a string regardless on the format of the data
+   * (Buffer, ArrayBuffer, ...) and returns a string representation of the payload.
+   * 
+   * @returns The string value of the payload of undefined if unable to process.
+   */
+  async readPayloadAsString(): Promise<string | undefined> {
+    const { payload } = this;
+    if (!payload) {
+      return undefined;
+    }
+    if (typeof payload === 'string') {
+      return payload;
+    }
+    if (payload.type === 'string') {
+      return payload.data as string;
+    }
+    if (['blob', 'file', 'formdata'].includes(payload.type)) {
+      // should this return a string from the blob?
+      return undefined;
+    }
+    const body = await this.readPayload();
+    if (hasBuffer && body instanceof Buffer) {
+      return body.toString();
+    }
+    const dataView = new DataView(body as ArrayBuffer);
+    const decoder = new TextDecoder();
+    return decoder.decode(dataView);
+  }
+}

package/src/models/Server.ts

@@ -0,0 +1,153 @@
+export const Kind = 'ARC#Server';
+
+export interface IServer {
+  kind: 'ARC#Server';
+  /**
+   * The base URI of the server.
+   * 
+   * Note, the URL can contain URI templates (e.g. `http://{host}.api.com/v1`)
+   * In this case the variable is replaced with the system or project variables.
+   * 
+   * For simplicity, the `uri` can be the full base URI with protocol, host, and the `basePath`
+   */
+  uri: string;
+  /**
+   * Usually included in the `uri`. When the `uri` is missing a protocol 
+   * this is then used.
+   */
+  protocol?: string;
+  /**
+   * The base path for the server. It starts with the `/`.
+   * When set, it is appended to the `uri` value.
+   */
+  basePath?: string;
+  /**
+   * Optional description of the server.
+   */
+  description?: string;
+}
+
+export class Server {
+  kind = Kind;
+  /**
+   * The base URI of the server.
+   * 
+   * Note, the URL can contain URI templates (e.g. `http://{host}.api.com/v1`)
+   * In this case the variable is replaced with the system or project variables.
+   * 
+   * For simplicity, the `uri` can be the full base URI with protocol, host, and the `basePath`
+   */
+  uri = '';
+  /**
+   * Usually included in the `uri`. When the `uri` is missing a protocol 
+   * this is then used.
+   */
+  protocol?: string;
+  /**
+   * The base path for the server. It starts with the `/`.
+   * When set, it is appended to the `uri` value.
+   */
+  basePath?: string;
+  /**
+   * Optional description of the server.
+   */
+  description?: string;
+
+  /**
+   * Creates a server definition from a base URI.
+   */
+  static fromUri(uri: string): Server {
+    const srv = new Server({
+      kind: Kind,
+      uri,
+    });
+    return srv;
+  }
+
+  /**
+   * @param input The server definition used to restore the state.
+   */
+  constructor(input?: string|IServer) {
+    let init: IServer;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      init = {
+        kind: Kind,
+        uri: '',
+      };
+    }
+    this.new(init);
+  }
+
+  /**
+   * Creates a new server clearing anything that is so far defined.
+   * 
+   * Note, this throws an error when the server is not an ARC server.
+   */
+  new(init: IServer): void {
+    if (!Server.isServer(init)) {
+      throw new Error(`Not an ARC server.`);
+    }
+    const { uri, description, protocol, basePath } = init;
+    this.kind = Kind;
+    this.uri = uri;
+    this.description = description;
+    this.protocol = protocol;
+    this.basePath = basePath;
+  }
+
+  /**
+   * Checks whether the input is a definition of a server.
+   */
+  static isServer(input: unknown): boolean {
+    const typed = input as IServer;
+    if (!input || typeof typed.uri === 'undefined' || typed.kind !== Kind) {
+      return false;
+    }
+    return true;
+  }
+
+  toJSON(): IServer {
+    const result: IServer = {
+      kind: Kind,
+      uri: this.uri,
+    };
+    if (this.description) {
+      result.description = this.description;
+    }
+    if (this.protocol) {
+      result.protocol = this.protocol;
+    }
+    if (this.basePath) {
+      result.basePath = this.basePath;
+    }
+    return result;
+  }
+
+  /**
+   * Constructs the final URI from the server configuration.
+   */
+  readUri(): string {
+    const { uri, protocol, basePath } = this;
+    let result = '';
+    if (!uri) {
+      return result;
+    }
+    
+    let tmp = uri;
+    if (protocol && !uri.includes('://')) {
+      tmp = `${protocol}//${uri}`;
+    }
+    result = tmp;
+    if (basePath) {
+      if (result.endsWith('/')) {
+        result = result.substring(0, result.length - 1);
+      }
+      result += basePath.startsWith('/') ? basePath : `/${basePath}`
+    }
+    return result;
+  }
+}

package/src/models/Thing.ts

@@ -0,0 +1,110 @@
+export const Kind = 'ARC#Thing';
+
+/**
+ * An interface describing a base metadata of a thing.
+ */
+export declare interface IThing {
+  /**
+   * The data kind. The application ignores the input with an unknown `kind`, unless it can be determined from the context.
+   */
+  kind?: 'ARC#Thing';
+  /**
+   * The name of the thing.
+   */
+  name?: string;
+  /**
+   * The description of the thing.
+   */
+  description?: string;
+  /**
+   * The version number of the thing.
+   */
+  version?: string;
+}
+
+export class Thing {
+  kind = Kind;
+  /**
+   * The name of the thing.
+   */
+  name?: string;
+  /**
+   * The description of the thing.
+   */
+  description?: string;
+  /**
+   * The version number of the thing.
+   */
+  version?: string;
+
+  /**
+   * Creates a basic description from a name.
+   */
+  static fromName(name: string): Thing {
+    const thing = new Thing({
+      name,
+      kind: Kind,
+    });
+    return thing;
+  }
+
+  /**
+   * @param input The thing definition used to restore the state.
+   */
+  constructor(input?: string | IThing) {
+    let init: IThing;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      init = {
+        kind: Kind,
+      };
+    }
+    this.new(init);
+  }
+
+  /**
+   * Creates a new thing clearing anything that is so far defined.
+   * 
+   * Note, this throws an error when the server is not an ARC thing.
+   */
+  new(init: IThing): void {
+    if (!Thing.isThing(init)) {
+      throw new Error(`Not an ARC thing.`);
+    }
+    const { description, name, version } = init;
+    this.kind = Kind;
+    this.name = name;
+    this.description = description;
+    this.version = version;
+  }
+
+  /**
+   * Checks whether the input is a definition of a server.
+   */
+  static isThing(input: unknown): boolean {
+    const typed = input as IThing;
+    if (input && typed.kind === Kind) {
+      return true;
+    }
+    return false;
+  }
+
+  toJSON(): IThing {
+    const result: IThing = {
+      kind: Kind,
+    };
+    if (this.name) {
+      result.name = this.name;
+    }
+    if (this.description) {
+      result.description = this.description;
+    }
+    if (this.version) {
+      result.version = this.version;
+    }
+    return result;
+  }
+}

package/src/models/Url.ts

@@ -0,0 +1,90 @@
+
+export interface IUrl {
+  /**
+   * A number of times the URL was used
+   */
+  cnt: number;
+  /**
+   * Last use timestamp.
+   */
+  time: number;
+  /**
+   * The request URL stored in the history.
+   */
+  url: string;
+  /**
+   * A timestamp of the midnight that corresponds to the `time` property.
+   */
+  midnight?: number;
+}
+
+/**
+ * An object representing an URL stored in the data store.
+ * This is an URL used to make a request.
+ */
+export class Url {
+  /**
+   * A number of times the URL was used
+   */
+  cnt = 0;
+  /**
+   * Last use timestamp.
+   */
+  time:number = Date.now();
+  /**
+   * The request URL stored in the history.
+   */
+  url = '';
+  /**
+   * A timestamp of the midnight that corresponds to the `time` property.
+   */
+  midnight?: number;
+
+  /**
+   * @param input The environment definition used to restore the state.
+   */
+  constructor(input: string|IUrl) {
+    let init: IUrl;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      init = {
+        cnt: 0,
+        time: Date.now(),
+        url: '',
+      };
+    }
+    this.new(init);
+  }
+
+  /**
+   * Creates a new environment clearing anything that is so far defined.
+   * 
+   * Note, this throws an error when the environment is not an ARC environment. 
+   */
+  new(init: IUrl): void {
+    const { url='', cnt=0, time = Date.now(), midnight } = init;
+    this.url = url;
+    this.cnt = cnt;
+    this.time = time;
+    if (midnight) {
+      this.midnight = midnight;
+    } else {
+      const d = new Date(this.time);
+      d.setHours(0, 0, 0, 0)
+      this.midnight = d.getTime();
+    }
+  }
+
+  toJSON(): IUrl {
+    const result: IUrl = {
+      url: this.url,
+      cnt: this.cnt,
+      time: this.time,
+      midnight: this.midnight,
+    };
+    return result;
+  }
+}

package/src/models/User.ts

@@ -0,0 +1,120 @@
+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 = 'ARC#User';
+
+/**
+ * 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 {
+  /**
+   * 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;
+}
+
+/**
+ * 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;
+}