@twin.org/blob-storage-service 0.0.1-next.21 → 0.0.1-next.23

package/dist/esm/index.mjs

@@ -3,6 +3,7 @@ import { BlobStorageTypes, BlobStorageConnectorFactory } from '@twin.org/blob-st
 import { StringHelper, Guards, ComponentFactory, Is, Converter, Coerce, GeneralError, Validation, ObjectHelper, Urn, NotFoundError } from '@twin.org/core';
 import { SchemaOrgTypes, SchemaOrgDataTypes } from '@twin.org/standards-schema-org';
 import { HttpStatusCode, HeaderTypes, MimeTypes, MimeTypeHelper } from '@twin.org/web';
+import { Sha256 } from '@twin.org/crypto';
 import { JsonLdHelper, JsonLdProcessor } from '@twin.org/data-json-ld';
 import { ComparisonOperator, LogicalOperator, SortDirection, EntitySchemaHelper, property, entity, EntitySchemaFactory } from '@twin.org/entity';
 import { EntityStorageConnectorFactory } from '@twin.org/entity-storage-models';
@@ -51,7 +52,7 @@ function generateRestRoutesBlobStorage(baseRouteName, componentName, options) {
                     request: {
                         body: {
                             blob: "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZw==",
-                            metadata: {
+                            annotationObject: {
                                 "@context": "https://schema.org",
                                 "@type": "DigitalDocument",
                                 name: "myfile.pdf"
@@ -80,7 +81,7 @@ function generateRestRoutesBlobStorage(baseRouteName, componentName, options) {
     };
     const blobStorageGetRoute = {
         operationId: `${camelTypeName}Get`,
-        summary: `Get the metadata for an item from ${lowerName}`,
+        summary: `Get the annotation for an item from ${lowerName}`,
         tag: options?.tagName ?? tagsBlobStorage[0].name,
         method: "GET",
         path: `${baseRouteName}/:id`,
@@ -109,14 +110,19 @@ function generateRestRoutesBlobStorage(baseRouteName, componentName, options) {
                         id: `${camelTypeName}GetResponseExample`,
                         response: {
                             body: {
-                                "@context": [BlobStorageTypes.ContextRoot, SchemaOrgTypes.ContextRoot],
+                                "@context": [
+                                    BlobStorageTypes.ContextRoot,
+                                    BlobStorageTypes.ContextRootCommon,
+                                    SchemaOrgTypes.ContextRoot
+                                ],
                                 type: BlobStorageTypes.Entry,
                                 id: "blob-memory:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70",
                                 dateCreated: "2024-01-01T00:00:00Z",
                                 encodingFormat: MimeTypes.Pdf,
                                 blobSize: 42,
+                                blobHash: "sha256:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70",
                                 fileExtension: "pdf",
-                                metadata: {
+                                annotationObject: {
                                     "@context": "https://schema.org",
                                     "@type": "DigitalDocument",
                                     name: "myfile.pdf"
@@ -135,14 +141,19 @@ function generateRestRoutesBlobStorage(baseRouteName, componentName, options) {
                         id: `${camelTypeName}GetResponseJsonLdExample`,
                         response: {
                             body: {
-                                "@context": [BlobStorageTypes.ContextRoot, SchemaOrgTypes.ContextRoot],
+                                "@context": [
+                                    BlobStorageTypes.ContextRoot,
+                                    BlobStorageTypes.ContextRootCommon,
+                                    SchemaOrgTypes.ContextRoot
+                                ],
                                 type: BlobStorageTypes.Entry,
                                 id: "blob-memory:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70",
                                 dateCreated: "2024-01-01T00:00:00Z",
                                 encodingFormat: MimeTypes.Pdf,
                                 blobSize: 42,
+                                blobHash: "sha256:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70",
                                 fileExtension: "pdf",
-                                metadata: {
+                                annotationObject: {
                                     "@context": "https://schema.org",
                                     "@type": "DigitalDocument",
                                     name: "myfile.pdf"
@@ -203,7 +214,7 @@ function generateRestRoutesBlobStorage(baseRouteName, componentName, options) {
     };
     const blobStorageUpdateRoute = {
         operationId: `${camelTypeName}Update`,
-        summary: `Update the metadata for an item in ${lowerName}`,
+        summary: `Update the annotation for an item in ${lowerName}`,
         tag: options?.tagName ?? tagsBlobStorage[0].name,
         method: "PUT",
         path: `${baseRouteName}/:id`,
@@ -218,7 +229,7 @@ function generateRestRoutesBlobStorage(baseRouteName, componentName, options) {
                             id: "blob-memory:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70"
                         },
                         body: {
-                            metadata: {
+                            annotationObject: {
                                 "@context": "https://schema.org",
                                 "@type": "DigitalDocument",
                                 name: "myfile.pdf"
@@ -287,18 +298,23 @@ function generateRestRoutesBlobStorage(baseRouteName, componentName, options) {
                         id: `${camelTypeName}ListResponseExample`,
                         response: {
                             body: {
-                                "@context": [BlobStorageTypes.ContextRoot],
+                                "@context": [BlobStorageTypes.ContextRoot, BlobStorageTypes.ContextRootCommon],
                                 type: BlobStorageTypes.EntryList,
                                 entries: [
                                     {
-                                        "@context": [BlobStorageTypes.ContextRoot, SchemaOrgTypes.ContextRoot],
+                                        "@context": [
+                                            BlobStorageTypes.ContextRoot,
+                                            BlobStorageTypes.ContextRootCommon,
+                                            SchemaOrgTypes.ContextRoot
+                                        ],
                                         type: BlobStorageTypes.Entry,
                                         id: "blob-memory:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70",
                                         dateCreated: "2024-01-01T00:00:00Z",
                                         encodingFormat: MimeTypes.Pdf,
                                         blobSize: 42,
+                                        blobHash: "sha256:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70",
                                         fileExtension: "pdf",
-                                        metadata: {
+                                        annotationObject: {
                                             "@context": "https://schema.org",
                                             "@type": "DigitalDocument",
                                             name: "myfile.pdf"
@@ -319,18 +335,23 @@ function generateRestRoutesBlobStorage(baseRouteName, componentName, options) {
                         id: `${camelTypeName}ListResponseJsonLdExample`,
                         response: {
                             body: {
-                                "@context": [BlobStorageTypes.ContextRoot],
+                                "@context": [BlobStorageTypes.ContextRoot, BlobStorageTypes.ContextRootCommon],
                                 type: BlobStorageTypes.EntryList,
                                 entries: [
                                     {
-                                        "@context": [BlobStorageTypes.ContextRoot, SchemaOrgTypes.ContextRoot],
+                                        "@context": [
+                                            BlobStorageTypes.ContextRoot,
+                                            BlobStorageTypes.ContextRootCommon,
+                                            SchemaOrgTypes.ContextRoot
+                                        ],
                                         type: BlobStorageTypes.Entry,
                                         id: "blob-memory:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70",
                                         dateCreated: "2024-01-01T00:00:00Z",
                                         encodingFormat: MimeTypes.Pdf,
                                         blobSize: 42,
+                                        blobHash: "sha256:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70",
                                         fileExtension: "pdf",
-                                        metadata: {
+                                        annotationObject: {
                                             "@context": "https://schema.org",
                                             "@type": "DigitalDocument",
                                             name: "myfile.pdf"
@@ -369,7 +390,7 @@ async function blobStorageCreate(httpRequestContext, componentName, request) {
     Guards.object(ROUTES_SOURCE, "request.body", request.body);
     Guards.stringBase64(ROUTES_SOURCE, "request.body.blob", request.body.blob);
     const component = ComponentFactory.get(componentName);
-    const id = await component.create(request.body.blob, request.body.encodingFormat, request.body.fileExtension, request.body.metadata, request.body.namespace, httpRequestContext.userIdentity, httpRequestContext.nodeIdentity);
+    const id = await component.create(request.body.blob, request.body.encodingFormat, request.body.fileExtension, request.body.annotationObject, request.body.namespace, httpRequestContext.userIdentity, httpRequestContext.nodeIdentity);
     return {
         statusCode: HttpStatusCode.created,
         headers: {
@@ -426,7 +447,7 @@ async function blobStorageGetContent(httpRequestContext, componentName, request)
     };
 }
 /**
- * Update the blob storage metadata.
+ * Update the blob storage annotation.
  * @param httpRequestContext The request context for the API.
  * @param componentName The name of the component to use in the routes.
  * @param request The request.
@@ -437,7 +458,7 @@ async function blobStorageUpdate(httpRequestContext, componentName, request) {
     Guards.object(ROUTES_SOURCE, "request.pathParams", request.pathParams);
     Guards.stringValue(ROUTES_SOURCE, "request.pathParams.id", request.pathParams.id);
     const component = ComponentFactory.get(componentName);
-    await component.update(request.pathParams.id, request.body.encodingFormat, request.body.fileExtension, request.body.metadata, httpRequestContext.userIdentity, httpRequestContext.nodeIdentity);
+    await component.update(request.pathParams.id, request.body.encodingFormat, request.body.fileExtension, request.body.annotationObject, httpRequestContext.userIdentity, httpRequestContext.nodeIdentity);
     return {
         statusCode: HttpStatusCode.noContent
     };
@@ -500,7 +521,7 @@ class BlobStorageService {
      */
     _defaultNamespace;
     /**
-     * The storage connector for the metadata.
+     * The storage connector for the annotation.
      * @internal
      */
     _entryEntityStorage;
@@ -544,17 +565,17 @@ class BlobStorageService {
         SchemaOrgDataTypes.registerRedirects();
     }
     /**
-     * Create the blob with some metadata.
+     * Create the blob with some annotation.
      * @param blob The data for the blob in base64 format.
      * @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 annotationObject Data for the custom annotation as JSON-LD.
      * @param 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.
      */
-    async create(blob, encodingFormat, fileExtension, metadata, namespace, userIdentity, nodeIdentity) {
+    async create(blob, encodingFormat, fileExtension, annotationObject, namespace, userIdentity, nodeIdentity) {
         Guards.stringBase64(this.CLASS_NAME, "blob", blob);
         if (this._includeUserIdentity) {
             Guards.stringValue(this.CLASS_NAME, "userIdentity", userIdentity);
@@ -577,11 +598,12 @@ class BlobStorageService {
             if (!Is.stringValue(fileExtension) && Is.stringValue(encodingFormat)) {
                 fileExtension = await MimeTypeHelper.defaultExtension(encodingFormat);
             }
-            if (Is.object(metadata)) {
+            if (Is.object(annotationObject)) {
                 const validationFailures = [];
-                JsonLdHelper.validate(metadata, validationFailures);
-                Validation.asValidationError(this.CLASS_NAME, "metadata", validationFailures);
+                JsonLdHelper.validate(annotationObject, validationFailures);
+                Validation.asValidationError(this.CLASS_NAME, "annotationObject", validationFailures);
             }
+            const blobHash = `sha256:${Converter.bytesToBase64(Sha256.sum256(storeBlob))}`;
             // If we have a vault connector then encrypt the data.
             if (this._vaultConnector) {
                 storeBlob = await this._vaultConnector.encrypt(`${nodeIdentity}/${this._vaultKeyId}`, VaultEncryptionType.ChaCha20Poly1305, storeBlob);
@@ -593,9 +615,10 @@ class BlobStorageService {
                 id: blobId,
                 dateCreated: new Date(Date.now()).toISOString(),
                 blobSize,
+                blobHash,
                 encodingFormat,
                 fileExtension,
-                metadata
+                annotationObject
             };
             const conditions = [];
             if (this._includeUserIdentity) {
@@ -616,7 +639,7 @@ class BlobStorageService {
     /**
      * Get the blob entry.
      * @param id The id of the blob to get in urn format.
-     * @param includeContent Include the content, or just get the metadata.
+     * @param includeContent Include the content, or just get the annotation.
      * @param userIdentity The user identity to use with storage operations.
      * @param nodeIdentity The node identity to use with storage operations.
      * @returns The entry and data for the blob if it can be found.
@@ -656,25 +679,24 @@ class BlobStorageService {
                 }
             }
             const jsonLd = this.entryToJsonLd(blobEntry, returnBlob);
-            const compacted = await JsonLdProcessor.compact(jsonLd, jsonLd["@context"]);
-            return compacted;
+            return JsonLdProcessor.compact(jsonLd);
         }
         catch (error) {
             throw new GeneralError(this.CLASS_NAME, "getFailed", undefined, error);
         }
     }
     /**
-     * Update the blob with metadata.
+     * Update the blob with annotation.
      * @param id The id of the blob entry to update.
      * @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 annotationObject Data for the custom annotation 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.
      */
-    async update(id, encodingFormat, fileExtension, metadata, userIdentity, nodeIdentity) {
+    async update(id, encodingFormat, fileExtension, annotationObject, userIdentity, nodeIdentity) {
         Urn.guard(this.CLASS_NAME, "id", id);
         if (this._includeUserIdentity) {
             Guards.stringValue(this.CLASS_NAME, "userIdentity", userIdentity);
@@ -687,10 +709,10 @@ class BlobStorageService {
             if (Is.undefined(blobEntry)) {
                 throw new NotFoundError(this.CLASS_NAME, "blobNotFound", id);
             }
-            if (Is.object(metadata)) {
+            if (Is.object(annotationObject)) {
                 const validationFailures = [];
-                await JsonLdHelper.validate(metadata, validationFailures);
-                Validation.asValidationError(this.CLASS_NAME, "metadata", validationFailures);
+                await JsonLdHelper.validate(annotationObject, validationFailures);
+                Validation.asValidationError(this.CLASS_NAME, "annotationObject", validationFailures);
             }
             // Now store the entry in entity storage
             const updatedBlobEntry = {
@@ -698,9 +720,10 @@ class BlobStorageService {
                 dateCreated: blobEntry.dateCreated,
                 dateModified: new Date(Date.now()).toISOString(),
                 blobSize: blobEntry.blobSize,
+                blobHash: blobEntry.blobHash,
                 encodingFormat: encodingFormat ?? blobEntry.encodingFormat,
                 fileExtension: fileExtension ?? blobEntry.fileExtension,
-                metadata: metadata ?? blobEntry.metadata
+                annotationObject: annotationObject ?? blobEntry.annotationObject
             };
             const conditions = [];
             if (this._includeUserIdentity) {
@@ -800,14 +823,17 @@ class BlobStorageService {
             ObjectHelper.propertyDelete(entity, "userIdentity");
         }
         const jsonLd = {
-            "@context": [BlobStorageTypes.ContextRoot, SchemaOrgTypes.ContextRoot],
+            "@context": [
+                BlobStorageTypes.ContextRoot,
+                BlobStorageTypes.ContextRootCommon,
+                SchemaOrgTypes.ContextRoot
+            ],
             type: BlobStorageTypes.EntryList,
             // The entries are never Partial as we don't allow custom property requests.
             entries: result.entities.map(entry => this.entryToJsonLd(entry)),
             cursor: result.cursor
         };
-        const compacted = await JsonLdProcessor.compact(jsonLd, jsonLd["@context"]);
-        return compacted;
+        return JsonLdProcessor.compact(jsonLd);
     }
     /**
      * Get the connector from the uri.
@@ -886,15 +912,20 @@ class BlobStorageService {
      */
     entryToJsonLd(entry, blob) {
         return {
-            "@context": [BlobStorageTypes.ContextRoot, SchemaOrgTypes.ContextRoot],
+            "@context": [
+                BlobStorageTypes.ContextRoot,
+                BlobStorageTypes.ContextRootCommon,
+                SchemaOrgTypes.ContextRoot
+            ],
             id: entry.id,
             type: BlobStorageTypes.Entry,
             dateCreated: entry.dateCreated,
             dateModified: entry.dateModified,
             blobSize: entry.blobSize,
+            blobHash: entry.blobHash,
             encodingFormat: entry?.encodingFormat,
             fileExtension: entry?.fileExtension,
-            metadata: entry?.metadata,
+            annotationObject: entry?.annotationObject,
             blob: Is.uint8Array(blob) ? Converter.bytesToBase64(blob) : undefined
         };
     }
@@ -920,6 +951,10 @@ let BlobStorageEntry = class BlobStorageEntry {
      * The length of the data in the blob.
      */
     blobSize;
+    /**
+     * The hash of the data in the blob.
+     */
+    blobHash;
     /**
      * The mime type for the blob.
      */
@@ -929,9 +964,9 @@ let BlobStorageEntry = class BlobStorageEntry {
      */
     fileExtension;
     /**
-     * The metadata for the blob as JSON-LD.
+     * The annotation object for the blob as JSON-LD.
      */
-    metadata;
+    annotationObject;
     /**
      * The user identity that created the blob.
      */
@@ -957,6 +992,10 @@ __decorate([
     property({ type: "number" }),
     __metadata("design:type", Number)
 ], BlobStorageEntry.prototype, "blobSize", void 0);
+__decorate([
+    property({ type: "string" }),
+    __metadata("design:type", String)
+], BlobStorageEntry.prototype, "blobHash", void 0);
 __decorate([
     property({ type: "string" }),
     __metadata("design:type", String)
@@ -968,7 +1007,7 @@ __decorate([
 __decorate([
     property({ type: "object", itemTypeRef: "IJsonLdNodeObject" }),
     __metadata("design:type", Object)
-], BlobStorageEntry.prototype, "metadata", void 0);
+], BlobStorageEntry.prototype, "annotationObject", void 0);
 __decorate([
     property({ type: "string" }),
     __metadata("design:type", String)

package/dist/types/blobStorageRoutes.d.ts

@@ -42,7 +42,7 @@ export declare function blobStorageGet(httpRequestContext: IHttpRequestContext,
  */
 export declare function blobStorageGetContent(httpRequestContext: IHttpRequestContext, componentName: string, request: IBlobStorageGetContentRequest): Promise<IBlobStorageGetContentResponse & IRestRouteResponseOptions>;
 /**
- * Update the blob storage metadata.
+ * Update the blob storage annotation.
  * @param httpRequestContext The request context for the API.
  * @param componentName The name of the component to use in the routes.
  * @param request The request.

package/dist/types/blobStorageService.d.ts

@@ -20,21 +20,21 @@ export declare class BlobStorageService implements IBlobStorageComponent {
      */
     constructor(options?: IBlobStorageServiceConstructorOptions);
     /**
-     * Create the blob with some metadata.
+     * Create the blob with some annotation.
      * @param blob The data for the blob in base64 format.
      * @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 annotationObject Data for the custom annotation as JSON-LD.
      * @param 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, encodingFormat?: string, fileExtension?: string, metadata?: IJsonLdNodeObject, namespace?: string, userIdentity?: string, nodeIdentity?: string): Promise<string>;
+    create(blob: string, encodingFormat?: string, fileExtension?: string, annotationObject?: IJsonLdNodeObject, namespace?: string, userIdentity?: string, nodeIdentity?: string): Promise<string>;
     /**
      * Get the blob entry.
      * @param id The id of the blob to get in urn format.
-     * @param includeContent Include the content, or just get the metadata.
+     * @param includeContent Include the content, or just get the annotation.
      * @param userIdentity The user identity to use with storage operations.
      * @param nodeIdentity The node identity to use with storage operations.
      * @returns The entry and data for the blob if it can be found.
@@ -42,17 +42,17 @@ export declare class BlobStorageService implements IBlobStorageComponent {
      */
     get(id: string, includeContent: boolean, userIdentity?: string, nodeIdentity?: string): Promise<IBlobStorageEntry>;
     /**
-     * Update the blob with metadata.
+     * Update the blob with annotation.
      * @param id The id of the blob entry to update.
      * @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 annotationObject Data for the custom annotation 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, encodingFormat?: string, fileExtension?: string, metadata?: IJsonLdNodeObject, userIdentity?: string, nodeIdentity?: string): Promise<void>;
+    update(id: string, encodingFormat?: string, fileExtension?: string, annotationObject?: IJsonLdNodeObject, userIdentity?: string, nodeIdentity?: string): Promise<void>;
     /**
      * Remove the blob.
      * @param id The id of the blob to remove in urn format.

package/dist/types/entities/blobStorageEntry.d.ts

@@ -19,6 +19,10 @@ export declare class BlobStorageEntry {
      * The length of the data in the blob.
      */
     blobSize: number;
+    /**
+     * The hash of the data in the blob.
+     */
+    blobHash: string;
     /**
      * The mime type for the blob.
      */
@@ -28,9 +32,9 @@ export declare class BlobStorageEntry {
      */
     fileExtension?: string;
     /**
-     * The metadata for the blob as JSON-LD.
+     * The annotation object for the blob as JSON-LD.
      */
-    metadata?: IJsonLdNodeObject;
+    annotationObject?: IJsonLdNodeObject;
     /**
      * The user identity that created the blob.
      */

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

@@ -4,7 +4,7 @@ import type { IBlobStorageServiceConfig } from "./IBlobStorageServiceConfig";
  */
 export interface IBlobStorageServiceConstructorOptions {
     /**
-     * The type of the storage connector for the metadata.
+     * The type of the storage connector for the annotation.
      * @default blob-storage-entry
      */
     entryEntityStorageType?: string;

package/docs/changelog.md

@@ -1,5 +1,5 @@
 # @twin.org/blob-storage-service - Changelog
 
-## v0.0.1-next.21
+## v0.0.1-next.23
 
 - Initial Release