@twin.org/blob-storage-models 0.0.1-next.8 → 0.0.1

package/dist/cjs/index.cjs

@@ -1,7 +1,174 @@
 'use strict';
 
+var dataCore = require('@twin.org/data-core');
 var core = require('@twin.org/core');
 
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The contexts of blob storage data.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const BlobStorageContexts = {
+    /**
+     * The context root for the blob storage types.
+     */
+    ContextRoot: "https://schema.twindev.org/blob-storage/",
+    /**
+     * The context root for the common types.
+     */
+    ContextRootCommon: "https://schema.twindev.org/common/"
+};
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The types of blob storage data.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const BlobStorageTypes = {
+    /**
+     * Represents blob storage entry.
+     */
+    Entry: "BlobStorageEntry",
+    /**
+     * Represents blob storage entry compression.
+     */
+    CompressionType: "BlobStorageCompressionType"
+};
+
+var $schema$1 = "https://json-schema.org/draft/2020-12/schema";
+var $id$1 = "https://schema.twindev.org/blob-storage/BlobStorageCompressionType";
+var description$1 = "The types of compression for blob storage data.";
+var type$1 = "string";
+var BlobStorageCompressionTypeSchema = {
+	$schema: $schema$1,
+	$id: $id$1,
+	description: description$1,
+	type: type$1,
+	"enum": [
+	"gzip",
+	"deflate"
+]
+};
+
+var $schema = "https://json-schema.org/draft/2020-12/schema";
+var $id = "https://schema.twindev.org/blob-storage/BlobStorageEntry";
+var description = "Interface describing a blob storage entry.";
+var type = "object";
+var properties = {
+	"@context": {
+		type: "array",
+		minItems: 2,
+		items: {
+			$ref: "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+		},
+		description: "JSON-LD Context.",
+		prefixItems: [
+			{
+				type: "string",
+				"const": "https://schema.twindev.org/blob-storage/"
+			},
+			{
+				type: "string",
+				"const": "https://schema.twindev.org/common/"
+			}
+		]
+	},
+	type: {
+		type: "string",
+		"const": "BlobStorageEntry",
+		description: "JSON-LD Type."
+	},
+	id: {
+		type: "string",
+		description: "The id for the blob."
+	},
+	dateCreated: {
+		type: "string",
+		description: "The date/time when the entry was created."
+	},
+	dateModified: {
+		type: "string",
+		description: "The date/time when the entry was modified."
+	},
+	blobSize: {
+		type: "number",
+		description: "The size of the data in the blob."
+	},
+	blobHash: {
+		type: "string",
+		description: "The hash of the data in the blob."
+	},
+	encodingFormat: {
+		type: "string",
+		description: "The mime type for the blob."
+	},
+	isEncrypted: {
+		type: "boolean",
+		description: "Indicates if the blob is encrypted."
+	},
+	compression: {
+		$ref: "https://schema.twindev.org/blob-storage/BlobStorageCompressionType",
+		description: "The type of compression used for the blob, if not set it is not stored with compression."
+	},
+	fileExtension: {
+		type: "string",
+		description: "The extension."
+	},
+	metadata: {
+		$ref: "https://schema.twindev.org/json-ld/JsonLdNodeObject",
+		description: "The metadata for the blob as JSON-LD."
+	},
+	blob: {
+		type: "string",
+		description: "The blob in base64 format, included if the includeContent flag was set in the request."
+	}
+};
+var required = [
+	"@context",
+	"type",
+	"id",
+	"dateCreated",
+	"blobSize",
+	"blobHash"
+];
+var additionalProperties = false;
+var BlobStorageEntrySchema = {
+	$schema: $schema,
+	$id: $id,
+	description: description,
+	type: type,
+	properties: properties,
+	required: required,
+	additionalProperties: additionalProperties
+};
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Handle all the data types for blob storage.
+ */
+class BlobStorageDataTypes {
+    /**
+     * Register all the data types.
+     */
+    static registerTypes() {
+        dataCore.DataTypeHandlerFactory.register(`${BlobStorageContexts.ContextRoot}${BlobStorageTypes.Entry}`, () => ({
+            context: BlobStorageContexts.ContextRoot,
+            type: BlobStorageTypes.Entry,
+            defaultValue: {},
+            jsonSchema: async () => BlobStorageEntrySchema
+        }));
+        dataCore.DataTypeHandlerFactory.register(`${BlobStorageContexts.ContextRoot}${BlobStorageTypes.CompressionType}`, () => ({
+            context: BlobStorageContexts.ContextRoot,
+            type: BlobStorageTypes.CompressionType,
+            defaultValue: {},
+            jsonSchema: async () => BlobStorageCompressionTypeSchema
+        }));
+    }
+}
+
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 /**
@@ -10,4 +177,25 @@ var core = require('@twin.org/core');
 // eslint-disable-next-line @typescript-eslint/naming-convention
 const BlobStorageConnectorFactory = core.Factory.createFactory("blob-storage");
 
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The types of compression for blob storage data.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const BlobStorageCompressionType = {
+    /**
+     * Gzip.
+     */
+    Gzip: "gzip",
+    /**
+     * Deflate.
+     */
+    Deflate: "deflate"
+};
+
+exports.BlobStorageCompressionType = BlobStorageCompressionType;
 exports.BlobStorageConnectorFactory = BlobStorageConnectorFactory;
+exports.BlobStorageContexts = BlobStorageContexts;
+exports.BlobStorageDataTypes = BlobStorageDataTypes;
+exports.BlobStorageTypes = BlobStorageTypes;

package/dist/esm/index.mjs

@@ -1,5 +1,172 @@
+import { DataTypeHandlerFactory } from '@twin.org/data-core';
 import { Factory } from '@twin.org/core';
 
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The contexts of blob storage data.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const BlobStorageContexts = {
+    /**
+     * The context root for the blob storage types.
+     */
+    ContextRoot: "https://schema.twindev.org/blob-storage/",
+    /**
+     * The context root for the common types.
+     */
+    ContextRootCommon: "https://schema.twindev.org/common/"
+};
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The types of blob storage data.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const BlobStorageTypes = {
+    /**
+     * Represents blob storage entry.
+     */
+    Entry: "BlobStorageEntry",
+    /**
+     * Represents blob storage entry compression.
+     */
+    CompressionType: "BlobStorageCompressionType"
+};
+
+var $schema$1 = "https://json-schema.org/draft/2020-12/schema";
+var $id$1 = "https://schema.twindev.org/blob-storage/BlobStorageCompressionType";
+var description$1 = "The types of compression for blob storage data.";
+var type$1 = "string";
+var BlobStorageCompressionTypeSchema = {
+	$schema: $schema$1,
+	$id: $id$1,
+	description: description$1,
+	type: type$1,
+	"enum": [
+	"gzip",
+	"deflate"
+]
+};
+
+var $schema = "https://json-schema.org/draft/2020-12/schema";
+var $id = "https://schema.twindev.org/blob-storage/BlobStorageEntry";
+var description = "Interface describing a blob storage entry.";
+var type = "object";
+var properties = {
+	"@context": {
+		type: "array",
+		minItems: 2,
+		items: {
+			$ref: "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
+		},
+		description: "JSON-LD Context.",
+		prefixItems: [
+			{
+				type: "string",
+				"const": "https://schema.twindev.org/blob-storage/"
+			},
+			{
+				type: "string",
+				"const": "https://schema.twindev.org/common/"
+			}
+		]
+	},
+	type: {
+		type: "string",
+		"const": "BlobStorageEntry",
+		description: "JSON-LD Type."
+	},
+	id: {
+		type: "string",
+		description: "The id for the blob."
+	},
+	dateCreated: {
+		type: "string",
+		description: "The date/time when the entry was created."
+	},
+	dateModified: {
+		type: "string",
+		description: "The date/time when the entry was modified."
+	},
+	blobSize: {
+		type: "number",
+		description: "The size of the data in the blob."
+	},
+	blobHash: {
+		type: "string",
+		description: "The hash of the data in the blob."
+	},
+	encodingFormat: {
+		type: "string",
+		description: "The mime type for the blob."
+	},
+	isEncrypted: {
+		type: "boolean",
+		description: "Indicates if the blob is encrypted."
+	},
+	compression: {
+		$ref: "https://schema.twindev.org/blob-storage/BlobStorageCompressionType",
+		description: "The type of compression used for the blob, if not set it is not stored with compression."
+	},
+	fileExtension: {
+		type: "string",
+		description: "The extension."
+	},
+	metadata: {
+		$ref: "https://schema.twindev.org/json-ld/JsonLdNodeObject",
+		description: "The metadata for the blob as JSON-LD."
+	},
+	blob: {
+		type: "string",
+		description: "The blob in base64 format, included if the includeContent flag was set in the request."
+	}
+};
+var required = [
+	"@context",
+	"type",
+	"id",
+	"dateCreated",
+	"blobSize",
+	"blobHash"
+];
+var additionalProperties = false;
+var BlobStorageEntrySchema = {
+	$schema: $schema,
+	$id: $id,
+	description: description,
+	type: type,
+	properties: properties,
+	required: required,
+	additionalProperties: additionalProperties
+};
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Handle all the data types for blob storage.
+ */
+class BlobStorageDataTypes {
+    /**
+     * Register all the data types.
+     */
+    static registerTypes() {
+        DataTypeHandlerFactory.register(`${BlobStorageContexts.ContextRoot}${BlobStorageTypes.Entry}`, () => ({
+            context: BlobStorageContexts.ContextRoot,
+            type: BlobStorageTypes.Entry,
+            defaultValue: {},
+            jsonSchema: async () => BlobStorageEntrySchema
+        }));
+        DataTypeHandlerFactory.register(`${BlobStorageContexts.ContextRoot}${BlobStorageTypes.CompressionType}`, () => ({
+            context: BlobStorageContexts.ContextRoot,
+            type: BlobStorageTypes.CompressionType,
+            defaultValue: {},
+            jsonSchema: async () => BlobStorageCompressionTypeSchema
+        }));
+    }
+}
+
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 /**
@@ -8,4 +175,21 @@ import { Factory } from '@twin.org/core';
 // eslint-disable-next-line @typescript-eslint/naming-convention
 const BlobStorageConnectorFactory = Factory.createFactory("blob-storage");
 
-export { BlobStorageConnectorFactory };
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The types of compression for blob storage data.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const BlobStorageCompressionType = {
+    /**
+     * Gzip.
+     */
+    Gzip: "gzip",
+    /**
+     * Deflate.
+     */
+    Deflate: "deflate"
+};
+
+export { BlobStorageCompressionType, BlobStorageConnectorFactory, BlobStorageContexts, BlobStorageDataTypes, BlobStorageTypes };

package/dist/types/dataTypes/blobStorageDataTypes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Handle all the data types for blob storage.
+ */
+export declare class BlobStorageDataTypes {
+    /**
+     * Register all the data types.
+     */
+    static registerTypes(): void;
+}

package/dist/types/index.d.ts

@@ -1,10 +1,18 @@
+export * from "./dataTypes/blobStorageDataTypes";
 export * from "./factories/blobStorageConnectorFactory";
 export * from "./models/api/IBlobStorageCreateRequest";
 export * from "./models/api/IBlobStorageGetContentRequest";
 export * from "./models/api/IBlobStorageGetContentResponse";
 export * from "./models/api/IBlobStorageGetRequest";
 export * from "./models/api/IBlobStorageGetResponse";
+export * from "./models/api/IBlobStorageListRequest";
+export * from "./models/api/IBlobStorageListResponse";
 export * from "./models/api/IBlobStorageRemoveRequest";
 export * from "./models/api/IBlobStorageUpdateRequest";
+export * from "./models/blobStorageCompressionType";
+export * from "./models/blobStorageContexts";
+export * from "./models/blobStorageTypes";
 export * from "./models/IBlobStorageComponent";
 export * from "./models/IBlobStorageConnector";
+export * from "./models/IBlobStorageEntry";
+export * from "./models/IBlobStorageEntryList";

package/dist/types/models/IBlobStorageComponent.d.ts

@@ -1,5 +1,9 @@
 import type { IComponent } from "@twin.org/core";
 import type { IJsonLdNodeObject } from "@twin.org/data-json-ld";
+import type { EntityCondition, SortDirection } from "@twin.org/entity";
+import type { BlobStorageCompressionType } from "./blobStorageCompressionType";
+import type { IBlobStorageEntry } from "./IBlobStorageEntry";
+import type { IBlobStorageEntryList } from "./IBlobStorageEntryList";
 /**
  * Interface describing an blob storage component.
  */
@@ -7,43 +11,73 @@ export interface IBlobStorageComponent extends IComponent {
     /**
      * Create the blob with some metadata.
      * @param blob The data for the blob in base64 format.
-     * @param mimeType Mime type for the blob, will be detected if left undefined.
-     * @param extension Extension for the blob, will be detected if left undefined.
+     * @param encodingFormat Mime type for the blob, will be detected if left undefined.
+     * @param fileExtension Extension for the blob, will be detected if left undefined.
      * @param metadata Data for the custom metadata as JSON-LD.
-     * @param namespace The namespace to use for storing, defaults to component configured namespace.
-     * @param nodeIdentity The node identity which controls the vault key.
+     * @param options Optional options for the creation of the blob.
+     * @param options.disableEncryption Disables encryption if enabled by default.
+     * @param options.overrideVaultKeyId Use a different vault key id for encryption, if not provided the default vault key id will be used.
+     * @param options.compress Optional compression type to use for the blob, defaults to no compression.
+     * @param options.namespace The namespace to use for storing, defaults to component configured namespace.
+     * @param userIdentity The user identity to use with storage operations.
+     * @param nodeIdentity The node identity to use with storage operations.
      * @returns The id of the stored blob in urn format.
      */
-    create(blob: string, mimeType?: string, extension?: string, metadata?: IJsonLdNodeObject, namespace?: string, nodeIdentity?: string): Promise<string>;
+    create(blob: string, encodingFormat?: string, fileExtension?: string, metadata?: IJsonLdNodeObject, options?: {
+        disableEncryption?: boolean;
+        overrideVaultKeyId?: string;
+        compress?: BlobStorageCompressionType;
+        namespace?: string;
+    }, userIdentity?: string, nodeIdentity?: string): Promise<string>;
     /**
      * Get the blob and metadata.
      * @param id The id of the blob to get in urn format.
-     * @param includeContent Include the content, or just get the metadata.
-     * @param nodeIdentity The node identity which controls the vault key.
+     * @param options Optional options for the retrieval of the blob.
+     * @param options.includeContent Include the content, or just get the metadata.
+     * @param options.overrideVaultKeyId Use a different vault key id for decryption, if not provided the default vault key id will be used.
+     * @param options.decompress If the content should be decompressed, if it was compressed when stored, defaults to true.
+     * @param userIdentity The user identity to use with storage operations.
+     * @param nodeIdentity The node identity to use with storage operations.
      * @returns The data and metadata for the blob if it can be found.
      * @throws Not found error if the blob cannot be found.
      */
-    get(id: string, includeContent: boolean, nodeIdentity?: string): Promise<{
-        blob?: string;
-        mimeType?: string;
-        extension?: string;
-        metadata?: IJsonLdNodeObject;
-    }>;
+    get(id: string, options?: {
+        includeContent?: boolean;
+        decompress?: boolean;
+        overrideVaultKeyId?: string;
+    }, userIdentity?: string, nodeIdentity?: string): Promise<IBlobStorageEntry>;
     /**
      * Update the blob with metadata.
      * @param id The id of the blob metadata to update.
-     * @param mimeType Mime type for the blob, will be detected if left undefined.
-     * @param extension Extension for the blob, will be detected if left undefined.
+     * @param encodingFormat Mime type for the blob, will be detected if left undefined.
+     * @param fileExtension Extension for the blob, will be detected if left undefined.
      * @param metadata Data for the custom metadata as JSON-LD.
+     * @param userIdentity The user identity to use with storage operations.
+     * @param nodeIdentity The node identity to use with storage operations.
      * @returns Nothing.
      * @throws Not found error if the blob cannot be found.
      */
-    update(id: string, mimeType?: string, extension?: string, metadata?: IJsonLdNodeObject): Promise<void>;
+    update(id: string, encodingFormat?: string, fileExtension?: string, metadata?: IJsonLdNodeObject, userIdentity?: string, nodeIdentity?: string): Promise<void>;
     /**
      * Remove the blob.
      * @param id The id of the blob to remove in urn format.
+     * @param userIdentity The user identity to use with storage operations.
+     * @param nodeIdentity The node identity to use with storage operations.
      * @returns Nothing.
      * @throws Not found error if the blob cannot be found.
      */
-    remove(id: string): Promise<void>;
+    remove(id: string, userIdentity?: string, nodeIdentity?: string): Promise<void>;
+    /**
+     * Query all the blob storage entries which match the conditions.
+     * @param conditions The conditions to match for the entries.
+     * @param orderBy The order for the results, defaults to created.
+     * @param orderByDirection The direction for the order, defaults to descending.
+     * @param cursor The cursor to request the next page of entries.
+     * @param pageSize The suggested number of entries to return in each chunk, in some scenarios can return a different amount.
+     * @param userIdentity The user identity to use with storage operations.
+     * @param nodeIdentity The node identity to use with storage operations.
+     * @returns All the entries for the storage matching the conditions,
+     * and a cursor which can be used to request more entities.
+     */
+    query(conditions?: EntityCondition<IBlobStorageEntry>, orderBy?: keyof Pick<IBlobStorageEntry, "dateCreated" | "dateModified">, orderByDirection?: SortDirection, cursor?: string, pageSize?: number, userIdentity?: string, nodeIdentity?: string): Promise<IBlobStorageEntryList>;
 }

package/dist/types/models/IBlobStorageEntry.d.ts

@@ -0,0 +1,65 @@
+import type { IJsonLdContextDefinitionElement, IJsonLdNodeObject } from "@twin.org/data-json-ld";
+import type { BlobStorageCompressionType } from "./blobStorageCompressionType";
+import type { BlobStorageContexts } from "./blobStorageContexts";
+import type { BlobStorageTypes } from "./blobStorageTypes";
+/**
+ * Interface describing a blob storage entry.
+ */
+export interface IBlobStorageEntry {
+    /**
+     * JSON-LD Context.
+     */
+    "@context": [
+        typeof BlobStorageContexts.ContextRoot,
+        typeof BlobStorageContexts.ContextRootCommon,
+        ...IJsonLdContextDefinitionElement[]
+    ];
+    /**
+     * JSON-LD Type.
+     */
+    type: typeof BlobStorageTypes.Entry;
+    /**
+     * The id for the blob.
+     */
+    id: string;
+    /**
+     * The date/time when the entry was created.
+     */
+    dateCreated: string;
+    /**
+     * The date/time when the entry was modified.
+     */
+    dateModified?: string;
+    /**
+     * The size of the data in the blob.
+     */
+    blobSize: number;
+    /**
+     * The hash of the data in the blob.
+     */
+    blobHash: string;
+    /**
+     * The mime type for the blob.
+     */
+    encodingFormat?: string;
+    /**
+     * Indicates if the blob is encrypted.
+     */
+    isEncrypted?: boolean;
+    /**
+     * The type of compression used for the blob, if not set it is not stored with compression.
+     */
+    compression?: BlobStorageCompressionType;
+    /**
+     * The extension.
+     */
+    fileExtension?: string;
+    /**
+     * The metadata for the blob as JSON-LD.
+     */
+    metadata?: IJsonLdNodeObject;
+    /**
+     * The blob in base64 format, included if the includeContent flag was set in the request.
+     */
+    blob?: string;
+}

package/dist/types/models/IBlobStorageEntryList.d.ts

@@ -0,0 +1,30 @@
+import type { IJsonLdContextDefinitionElement } from "@twin.org/data-json-ld";
+import type { SchemaOrgContexts, SchemaOrgTypes } from "@twin.org/standards-schema-org";
+import type { BlobStorageContexts } from "./blobStorageContexts";
+import type { IBlobStorageEntry } from "./IBlobStorageEntry";
+/**
+ * Interface describing an blob storage entry list.
+ */
+export interface IBlobStorageEntryList {
+    /**
+     * JSON-LD Context.
+     */
+    "@context": [
+        typeof SchemaOrgContexts.ContextRoot,
+        typeof BlobStorageContexts.ContextRoot,
+        typeof BlobStorageContexts.ContextRootCommon,
+        ...IJsonLdContextDefinitionElement[]
+    ];
+    /**
+     * JSON-LD Type.
+     */
+    type: typeof SchemaOrgTypes.ItemList;
+    /**
+     * The list of entries.
+     */
+    [SchemaOrgTypes.ItemListElement]: IBlobStorageEntry[];
+    /**
+     * The cursor to get the next chunk of entries.
+     */
+    [SchemaOrgTypes.NextItem]?: string;
+}

package/dist/types/models/api/IBlobStorageCreateRequest.d.ts

@@ -1,4 +1,5 @@
 import type { IJsonLdNodeObject } from "@twin.org/data-json-ld";
+import type { BlobStorageCompressionType } from "../blobStorageCompressionType";
 /**
  * Request to create an entry in blob storage.
  */
@@ -14,15 +15,29 @@ export interface IBlobStorageCreateRequest {
         /**
          * The mime type of the blob, will be detected if left undefined.
          */
-        mimeType?: string;
+        encodingFormat?: string;
         /**
          * The extension of the blob, will be detected if left undefined.
          */
-        extension?: string;
+        fileExtension?: string;
         /**
          * Custom metadata to associate with the blob as JSON-LD.
          */
         metadata?: IJsonLdNodeObject;
+        /**
+         * Disables encryption if enabled by default.
+         * @default false
+         */
+        disableEncryption?: boolean;
+        /**
+         * Optional compression type to use for the blob, defaults to no compression.
+         */
+        compress?: BlobStorageCompressionType;
+        /**
+         * Use a different vault key id for encryption, if not provided the default vault key id will be used.
+         * @default undefined
+         */
+        overrideVaultKeyId?: string;
         /**
          * The namespace to store the data in, defaults to component configured namespace.
          */

package/dist/types/models/api/IBlobStorageGetContentRequest.d.ts

@@ -15,12 +15,22 @@ export interface IBlobStorageGetContentRequest {
      * The query parameters.
      */
     query?: {
+        /**
+         * If the content should be decompressed, if it was compressed when stored, defaults to true.
+         * @default true
+         */
+        decompress?: boolean | string;
+        /**
+         * Use a different vault key id for decryption, if not provided the default vault key id will be used.
+         * @default undefined
+         */
+        overrideVaultKeyId?: string;
         /**
          * Set the download flag which should prompt the browser to save the file.
          * Otherwise the browser should show the content inside the page.
          * @default false
          */
-        download?: boolean;
+        download?: boolean | string;
         /**
          * Set the filename to use when a download is triggered.
          * A filename will be generated if not provided.