@api-client/core 0.6.4 → 0.6.7

package/src/models/data/DataProperty.ts

@@ -0,0 +1,306 @@
+import { IThing, Thing } from "../Thing.js";
+import v4 from '../../lib/uuid.js';
+import { DataNamespace } from "./DataNamespace.js";
+import { IDataPropertySchema } from "./DataPropertySchema.js";
+
+export type DataPropertyType = 'string' | 'number' | 'nil' | 'boolean' | 'date' | 'datetime' |
+  'time' | 'bytes' | 'any' | 'file';
+export const DataPropertyTypes: DataPropertyType[] = [
+  'string', 'number', 'nil', 'boolean', 'date', 'datetime', 'time', 'bytes', 'any', 'file'
+];
+
+export enum DataPropertyList {
+  string = 'string',
+  number = 'number',
+  nil = 'nil',
+  boolean = 'boolean',
+  date = 'date',
+  datetime = 'datetime',
+  time = 'time',
+  bytes = 'bytes',
+  any = 'any',
+  file = 'file',
+}
+
+export const Kind = 'Core#DataProperty';
+
+export interface IPropertySchema<T> {
+  /**
+   * Whether it is a general schema for the property.
+   * All other schemas inherit from this one. This allows creating global schema description 
+   * like examples, default values, minimum value, etc and then use it as a base to generate specific formats.
+   * 
+   * A property may not have a global schema.
+   */
+  global?: boolean;
+  /**
+   * The mime type this schema describes.
+   * For JSON it is `application/json`, for XML it is `application/xml` (or `text/xml`) adn so on.
+   * 
+   * Note, when this value is missing then it is assumed that the schema is `global`.
+   */
+  format?: string;
+  /**
+   * The schema definition.
+   */
+  value: IDataPropertySchema<T>;
+}
+
+export interface IDataProperty {
+  kind: typeof Kind;
+  /**
+   * The key of the namespace.
+   */
+  key: string;
+  /**
+   * The data property description.
+   */
+  info: IThing;
+  /**
+   * Wether the data property is required.
+   */
+  required?: boolean;
+  /**
+   * Whether the data property allows multiple items.
+   */
+  multiple?: boolean;
+  /**
+   * Whether this property describes a primary key of the entity.
+   */
+  primary?: boolean;
+  /**
+   * Whether this property describes an indexed property of the entity.
+   */
+  index?: boolean;
+  /**
+   * Optional general purpose tags for the UI.
+   */
+  tags?: string[];
+  /**
+   * For future use.
+   * 
+   * The keys of the taxonomy items associated with the property.
+   */
+  taxonomy?: string[];
+  /**
+   * The data type for this property.
+   * Note, not all schemas support the same type. For example, defining `sint32` 
+   * works for protocol buffers but does not for JSON. In such case we use default 
+   * translation `sint32` -> `number`. Another way it to create 
+   * a derivative entity for specific schema to describe specific schema case.
+   */
+  type: DataPropertyType;
+
+  /**
+   * While the `DataProperty` describes the general shape of the data and can be used to 
+   * model the structure of the data in the system, a schema describes hwo the data 
+   * should be serialized into a specific format. This allows adding example values,
+   * default values, specifying data format, etc. The assumption here is
+   * that with enough specifics provided by the user (a domain specialist)
+   * we can automatically generate a schema for the given format.
+   */
+  schemas?: IPropertySchema<unknown>[];
+}
+
+export class DataProperty {
+  kind = Kind;
+
+  key = '';
+
+  /**
+   * The description of the data namespace.
+   */
+  info: Thing = Thing.fromName('');
+
+  /**
+   * Wether the data property is required.
+   */
+  required?: boolean;
+
+  /**
+   * Whether the data property allows multiple items.
+   */
+  multiple?: boolean;
+
+  /**
+   * Whether this property describes a primary key of the entity.
+   */
+  primary?: boolean;
+
+  /**
+   * Whether this property describes an indexed property of the entity.
+   */
+  index?: boolean;
+
+  /**
+   * Optional general purpose tags for the UI.
+   */
+  tags: string[] = [];
+
+  /**
+   * Reserved for future use.
+   * 
+   * The keys of the taxonomy items associated with the property.
+   */
+  taxonomy: string[] = [];
+
+  /**
+   * The data type for this property.
+   * Note, not all schemas support the same type. For example, defining `sint32` 
+   * works for protocol buffers but does not for JSON. In such case we use default 
+   * translation `sint32` -> `number`. Another way it to create 
+   * a derivative entity for specific schema to describe specific schema case.
+   */
+  type: DataPropertyType = 'string';
+
+  /**
+   * While the `DataProperty` describes the general shape of the data and can be used to 
+   * model the structure of the data in the system, a schema describes hwo the data 
+   * should be serialized into a specific format. This allows adding example values,
+   * default values, specifying data format, etc. The assumption here is
+   * that with enough specifics provided by the user (a domain specialist)
+   * we can automatically generate a schema for the given format.
+   */
+  schemas: IPropertySchema<unknown>[] = [];
+
+  static get supportedTypes(): DataPropertyType[] {
+    return [...DataPropertyTypes];
+  }
+
+  static fromName(root: DataNamespace, name: string): DataProperty {
+    const property = new DataProperty(root);
+    property.info = Thing.fromName(name);
+    return property;
+  }
+
+  static fromType(root: DataNamespace, type: DataPropertyType): DataProperty {
+    const assoc = new DataProperty(root);
+    assoc.type = type;
+    return assoc;
+  }
+
+  /**
+   * @param input The data property definition to restore.
+   */
+  constructor(protected root: DataNamespace, input?: string | IDataProperty) {
+    let init: IDataProperty;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      init = {
+        kind: Kind,
+        key: v4(),
+        info: Thing.fromName('').toJSON(),
+        type: 'string',
+      };
+    }
+    this.new(init);
+  }
+
+  new(init: IDataProperty): void {
+    if (!DataProperty.isDataProperty(init)) {
+      throw new Error(`Not a data property.`);
+    }
+    const { info, key = v4(), kind = Kind, multiple, required, type = DataPropertyList.string, index, primary, tags, taxonomy, schemas } = init;
+    this.kind = kind;
+    this.key = key;
+    this.type = type;
+    if (info) {
+      this.info = new Thing(info);
+    } else {
+      this.info = Thing.fromName('');
+    }
+    if (typeof multiple === 'boolean') {
+      this.multiple = multiple;
+    } else {
+      this.multiple = undefined;
+    }
+    if (typeof required === 'boolean') {
+      this.required = required;
+    } else {
+      this.required = undefined;
+    }
+    if (typeof index === 'boolean') {
+      this.index = index;
+    } else {
+      this.index = undefined;
+    }
+    if (typeof primary === 'boolean') {
+      this.primary = primary;
+    } else {
+      this.primary = undefined;
+    }
+    if (Array.isArray(tags)) {
+      this.tags = [...tags];
+    } else {
+      this.tags = [];
+    }
+    if (Array.isArray(taxonomy)) {
+      this.taxonomy = [...taxonomy];
+    } else {
+      this.taxonomy = [];
+    }
+    if (Array.isArray(schemas)) {
+      this.schemas = schemas.map(i => ({ ...i }));
+    } else {
+      this.schemas = [];
+    }
+  }
+
+  static isDataProperty(input: unknown): boolean {
+    const typed = input as IDataProperty;
+    if (!input || typed.kind !== Kind) {
+      return false;
+    }
+    return true;
+  }
+
+  toJSON(): IDataProperty {
+    const result: IDataProperty = {
+      kind: Kind,
+      info: this.info.toJSON(),
+      key: this.key,
+      type: this.type || DataPropertyList.string,
+    };
+    if (typeof this.index === 'boolean') {
+      result.index = this.index;
+    }
+    if (typeof this.primary === 'boolean') {
+      result.primary = this.primary;
+    }
+    if (typeof this.multiple === 'boolean') {
+      result.multiple = this.multiple;
+    }
+    if (typeof this.required === 'boolean') {
+      result.required = this.required;
+    }
+    if (Array.isArray(this.tags) && this.tags.length) {
+      result.tags = [...this.tags];
+    }
+    if (Array.isArray(this.taxonomy) && this.taxonomy.length) {
+      result.taxonomy = [...this.taxonomy];
+    }
+    if (Array.isArray(this.schemas) && this.schemas.length) {
+      result.schemas = this.schemas.map(i => ({ ...i }));
+    }
+    return result;
+  }
+
+  /**
+   * Removes self from the parent entity and the namespace definition.
+   */
+  remove(): void {
+    const { root } = this;
+    const entity = root.definitions.entities.find(i => i.properties.some(j => j === this));
+    if (entity) {
+      const assocIndex = entity.properties.findIndex(i => i === this);
+      entity.properties.splice(assocIndex, 1);
+    }
+    const defIndex = this.root.definitions.properties.findIndex(i => i.key === this.key);
+    if (defIndex >= 0) {
+      this.root.definitions.properties.splice(defIndex, 1);
+    }
+  }
+}

package/src/models/data/DataPropertySchema.ts

@@ -0,0 +1,156 @@
+export type NumberFormat = 'integer' | 'float' | 'long' | 'double' | 'int32' | 'int64' | 'uint32' | 'uint64' |
+  'sint32' | 'sint64' | 'fixed32' | 'fixed64' | 'sfixed32' | 'sfixed64';
+export const NumberFormats: NumberFormat[] = [
+  'integer', 'float', 'long', 'double', 'int32', 'int64', 'uint32', 'uint64', 'sint32', 'sint64', 'fixed32', 'fixed64',
+  'sfixed32', 'sfixed64'
+];
+
+export enum NumberFormatList {
+  integer = 'integer',
+  float = 'float',
+  int32 = 'int32',
+  int64 = 'int64',
+  uint32 = 'uint32',
+  uint64 = 'uint64',
+  sint32 = 'sint32',
+  sint64 = 'sint64',
+  fixed32 = 'fixed32',
+  fixed64 = 'fixed64',
+  sfixed32 = 'sfixed32',
+  sfixed64 = 'sfixed64',
+  double = 'double',
+}
+
+export type DateFormat = 'rfc3339' | 'rfc2616';
+export const DateFormats: DateFormat[] = ['rfc3339', 'rfc2616'];
+export enum DateFormatList {
+  /**
+   * The "date-time" notation of RFC3339
+   */
+  rfc3339 = 'rfc3339',
+  /**
+   * The format defined in RFC2616.
+   */
+  rfc2616 = 'rfc2616',
+}
+
+/**
+ * The difference between the DataProperty and this is that the `DataProperty` describes the general shape of 
+ * the data and `IDataPropertySchema` describes how this property is translated into a specific format
+ * (like JSON, Protocol Buffer, XML, etc)
+ */
+export interface IDataPropertySchema<T> {
+  // Common
+
+  /**
+   * The default value for the property.
+   */
+  default?: T;
+
+  /**
+   * Enum values for the property.
+   */
+  enum?: T[];
+
+  /**
+   * The example value for the property.
+   */
+  examples?: T[];
+
+  /**
+   * The format of a `number` or `datetime` type.
+   */
+  format?: NumberFormat | DateFormat;
+
+  /**
+   * Minimum length of the string or a file. Value MUST be equal to or greater than 0.
+   */
+  minLength?: number;
+  
+  /**
+   * The minimum length of the string or a file. Value MUST be equal to or greater than 0.
+   */
+  maxLength?: number;
+
+
+  // STRING
+
+  /**
+   * Regular expression that this string MUST match.
+   */
+  pattern?: string;
+
+  // NUMBER
+
+  /**
+   * The minimum value.
+   */
+  minimum?: number;
+
+  /**
+   * The maximum value.
+   */
+  maximum?: number;
+
+  /**
+   * A numeric instance is valid against "multipleOf" if the result of dividing the instance by this 
+   * value is an integer.
+   */
+  multipleOf?: number;
+
+  // File
+
+  /**
+   * A list of valid content-type strings for the file. The file type `*\/*` is a valid value.
+   */
+  fileTypes?: string[];
+
+  // XML serialization
+
+  /**
+   * Describes XML specific serialization.
+   */
+  xml?: {
+    /**
+     * Whether is property should be represented as an attribute of the parent entity.
+     * 
+     * ```
+     * <Person name="John Doe"></Person>
+     * ```
+     */
+    attribute?: boolean;
+
+    /**
+     * The name of the attribute or a wrapped property to use when serializing the property.
+     * 
+     * ```
+     * <Person fullName="John Doe"></Person>
+     * ```
+     */
+    name?: string;
+
+    /**
+     * When the property is an array (has the `multiple` set to true)
+     * then it tells that the list of values should be wrapped with a parent
+     * element:
+     * 
+     * ```
+     * <Person>
+     *  <Person fullName="John Doe"></Person>
+     * </Person>
+     * ```
+     * 
+     * Use this with the combination with `name` to describe the name of the wrapped
+     * element
+     * 
+     * ```
+     * <people>
+     *  <Person fullName="John Doe"></Person>
+     * </people>
+     * ```
+     * 
+     * Note, this is mutually exclusive with `attribute`.
+     */
+    wrapped?: boolean;
+  }
+}

package/src/models/legacy/Normalizer.ts

@@ -2,7 +2,7 @@
 import { ARCHistoryRequest, ARCSavedRequest } from './request/ArcRequest.js';
 import { TransformedPayload as LegacyTransformedPayload } from './request/ArcResponse.js';
 import { IRequestAuthorization, Kind as AuthKind } from '../RequestAuthorization.js';
-import { hasBuffer } from '../../lib/transformers/PayloadSerializer.js';
+import { hasBuffer } from '../../Platform.js';
 
 export class Normalizer {
   static normalizeRequest(request: unknown): ARCHistoryRequest | ARCSavedRequest | undefined {

package/src/models/store/File.ts

@@ -310,7 +310,7 @@ export class StoredFile {
       throw new Error(`The user is required.`);
     }
     if (user.kind !== UserKind) {
-      throw new Error(`Invalid value for the user when setting "lastModified".`);
+      throw new Error(`Invalid value for the user when setting "deletedInfo".`);
     }
     this[deletedSymbol] = true;
     this[deletedInfoSymbol] = {
@@ -387,6 +387,60 @@ export class StoredFile {
       file.lastModified.byMe = file.lastModified.user === user;
     }
   }
+
+  /**
+   * Static method to set the `lastModified` property on a file without creating an instance of a file meta.
+   * Useful when the meta kind is unknown.
+   * 
+   * @param file The file to update. Note, this method mutates the file.
+   * @param user The user that modifies the file.
+   * @returns The same file.
+   */
+  static setLastModified(file: IFile, user: IUser): IFile {
+    if (!file) {
+      throw new Error(`The file is required.`);
+    }
+    if (!user) {
+      throw new Error(`The user is required.`);
+    }
+    if (user.kind !== UserKind) {
+      throw new Error(`Invalid value for the user when setting "lastModified".`);
+    }
+    file.lastModified = {
+      byMe: false,
+      time: Date.now(),
+      user: user.key,
+      name: user.name,
+    };
+    return file;
+  }
+
+  /**
+   * Similar to the instance method `setDeleted()` but without creating an instance of the file when the type is unknown.
+   * 
+   * @param file The file to change. Note, this operation mutates the file.
+   * @param user The deleting user
+   * @returns The same file reference.
+   */
+  static setDeleted(file: IFile, user: IUser): IFile {
+    if (!file) {
+      throw new Error(`The file is required.`);
+    }
+    if (!user) {
+      throw new Error(`The user is required.`);
+    }
+    if (user.kind !== UserKind) {
+      throw new Error(`Invalid value for the user when setting "deletedInfo".`);
+    }
+    file.deleted = true;
+    file.deletedInfo = {
+      byMe: false,
+      time: Date.now(),
+      user: user.key,
+      name: user.name,
+    };
+    return file;
+  }
 }
 
 export class File extends StoredFile {

package/src/runtime/store/FilesSdk.ts

@@ -6,10 +6,10 @@ import { IUser } from '../../models/store/User.js';
 import { IFile } from '../../models/store/File.js';
 import { Kind as ProjectKind } from '../../models/Project.js';
 import { Kind as WorkspaceKind } from '../../models/Workspace.js';
-import { IHttpProject } from '../../models/HttpProject.js';
+import { Kind as DataNamespaceKind } from '../../models/data/DataNamespace.js';
 import { SdkError } from './Errors.js';
 
-export interface IFileCreateOptions {
+export interface IMetaCreateOptions {
   /**
    * Optional parent file id.
    * When set it creates a file under this parent.
@@ -17,19 +17,41 @@ export interface IFileCreateOptions {
   parent?: string;
 }
 
+export interface IMediaCreateOptions {
+  /**
+   * Optional contents mime type.
+   * Default to `application/json`.
+   */
+  mime?: string;
+}
+
+export interface IFileCreateOptions extends IMetaCreateOptions, IMediaCreateOptions {
+
+}
+
+export type FileKind = typeof ProjectKind | typeof WorkspaceKind | typeof DataNamespaceKind;
+
+/**
+ * In the store, the file is represented by the meta and the media.
+ * 
+ * The meta is used to represent the file in the UI when listing files or presenting their metadata (like name, last modified, etc).
+ * The media is the actual contents of the file and is only used by application specializing in this file modification.
+ */
 export class FilesSdk extends SdkBase {
   /**
    * Lists files (spaces, projects, etc) in the store.
    * 
-   * @param kinds the list of kinds to list. Spaces are always included.
+   * @param kinds Optional list of kinds to limit the file types in the result. Spaces are always included.
    * @param options Optional query options.
    * @param request Optional request options.
    */
-  async list(kinds: (typeof ProjectKind | typeof WorkspaceKind)[], options?: IListOptions, request: ISdkRequestOptions = {}): Promise<IListResponse<IFile>> {
+  async list(kinds?: FileKind[], options?: IListOptions, request: ISdkRequestOptions = {}): Promise<IListResponse<IFile>> {
     const token = request.token || this.sdk.token;
     const url = this.sdk.getUrl(RouteBuilder.files());
     this.sdk.appendListOptions(url, options);
-    kinds.forEach(k => url.searchParams.append('kind', k));
+    if (Array.isArray(kinds)) {
+      kinds.forEach(k => url.searchParams.append('kind', k));
+    }
     const result = await this.sdk.http.get(url.toString(), { token });
     this.inspectCommonStatusCodes(result.status, result.body);
     const E_PREFIX = 'Unable to list files. ';
@@ -57,20 +79,44 @@ export class FilesSdk extends SdkBase {
     return data;
   }
 
+  /**
+   * Creates both the meta and the media for a file.
+   * 
+   * @param meta The file meta
+   * @param contents The file contents
+   * @param opts Meta and media create options. 
+   * @param request Optional request details
+   * @returns The id of the created file meta.
+   */
+  async create(meta: IFile, contents: unknown, opts: IFileCreateOptions = {}, request: ISdkRequestOptions = {}): Promise<string> {
+    const id = await this.createMeta(meta, opts, request);
+    await this.createMedia(contents, id, opts, request);
+    return id;
+  }
+
   /**
    * Creates a file in the store.
    * 
-   * @param file The definition of a file that extends the IFile interface or one of the supported by the server schemas.
+   * @param file The definition of a file that extends the IFile interface.
    * @param opts Optional options when creating a file
    * @param request Optional request options.
    * @returns The key of the creates file.
    */
-  async create(file: IFile | IHttpProject, opts: IFileCreateOptions = {}, request: ISdkRequestOptions = {}): Promise<string> {
+  async createMeta(file: IFile, opts: IMetaCreateOptions = {}, request: ISdkRequestOptions = {}): Promise<string> {
     const token = request.token || this.sdk.token;
-    const path = opts.parent ? RouteBuilder.file(opts.parent) : RouteBuilder.files();
+    const path = RouteBuilder.files();
     const url = this.sdk.getUrl(path);
+    if (opts.parent) {
+      url.searchParams.set('parent', opts.parent);
+    }
     const body = JSON.stringify(file);
-    const result = await this.sdk.http.post(url.toString(), { token, body });
+    const result = await this.sdk.http.post(url.toString(), { 
+      token, 
+      body,
+      headers: {
+        'content-type': 'application/json'
+      },
+    });
     this.inspectCommonStatusCodes(result.status, result.body);
     const E_PREFIX = 'Unable to create a file. ';
     if (result.status !== 204) {
@@ -90,6 +136,46 @@ export class FilesSdk extends SdkBase {
     return id as string;
   }
 
+  /**
+   * Creates a file contents (the media) after the file meta was created.
+   * 
+   * @param contents The file contents to upload to the server.
+   * @param key The created file meta key.
+   * @param opts Contents create options. You can define content's mime type here.
+   * @param request Optional request.
+   */
+  async createMedia(contents: unknown, key: string, opts: IMediaCreateOptions = {}, request: ISdkRequestOptions = {}): Promise<void> {
+    const token = request.token || this.sdk.token;
+    const path = RouteBuilder.file(key);
+    const url = this.sdk.getUrl(path);
+    url.searchParams.set('alt', 'media');
+    const mime = opts.mime || 'application/json';
+    let body: string;
+    if (mime.includes('json')) {
+      body = JSON.stringify(contents);
+    } else {
+      body = String(contents);
+    }
+    const result = await this.sdk.http.put(url.toString(), { 
+      token, 
+      body,
+      headers: {
+        'content-type': mime
+      },
+    });
+    this.inspectCommonStatusCodes(result.status, result.body);
+    const E_PREFIX = 'Unable to create a file. ';
+    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;
+    }
+  }
+
   /**
    * Reads file metadata from the store.
    * 

package/src/runtime/store/Http.ts

@@ -14,5 +14,7 @@ export abstract class Http extends SdkBase {
 
   abstract patch(url: string, opts?: IStoreRequestOptions): Promise<IStoreResponse>;
 
+  abstract put(url: string, opts?: IStoreRequestOptions): Promise<IStoreResponse>;
+
   abstract delete(url: string, opts?: IStoreRequestOptions): Promise<IStoreResponse>;
 }