@twin.org/document-management-models 0.0.1-next.1 → 0.0.1-next.11

package/dist/cjs/index.cjs

@@ -3,10 +3,10 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 /**
- * The types of document management objects.
+ * The contexts of document management objects.
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
-const DocumentTypes = {
+const DocumentContexts = {
     /**
      * The context root for the document types.
      */
@@ -14,15 +14,29 @@ const DocumentTypes = {
     /**
      * The context root for the common types.
      */
-    ContextRootCommon: "https://schema.twindev.org/common/",
+    ContextRootCommon: "https://schema.twindev.org/common/"
+};
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The types of document management objects.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const DocumentTypes = {
     /**
      * Represents a document.
      */
     Document: "Document",
+    /**
+     * Represents a document attestation.
+     */
+    DocumentAttestation: "DocumentAttestation",
     /**
      * Represents a document list.
      */
     DocumentList: "DocumentList"
 };
 
+exports.DocumentContexts = DocumentContexts;
 exports.DocumentTypes = DocumentTypes;

package/dist/esm/index.mjs

@@ -1,10 +1,10 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 /**
- * The types of document management objects.
+ * The contexts of document management objects.
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
-const DocumentTypes = {
+const DocumentContexts = {
     /**
      * The context root for the document types.
      */
@@ -12,15 +12,28 @@ const DocumentTypes = {
     /**
      * The context root for the common types.
      */
-    ContextRootCommon: "https://schema.twindev.org/common/",
+    ContextRootCommon: "https://schema.twindev.org/common/"
+};
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The types of document management objects.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const DocumentTypes = {
     /**
      * Represents a document.
      */
     Document: "Document",
+    /**
+     * Represents a document attestation.
+     */
+    DocumentAttestation: "DocumentAttestation",
     /**
      * Represents a document list.
      */
     DocumentList: "DocumentList"
 };
 
-export { DocumentTypes };
+export { DocumentContexts, DocumentTypes };

package/dist/types/index.d.ts

@@ -1,10 +1,13 @@
+export * from "./models/api/IDocumentManagementCreateRequest";
 export * from "./models/api/IDocumentManagementGetRequest";
 export * from "./models/api/IDocumentManagementGetResponse";
 export * from "./models/api/IDocumentManagementQueryRequest";
 export * from "./models/api/IDocumentManagementQueryResponse";
 export * from "./models/api/IDocumentManagementRemoveRequest";
-export * from "./models/api/IDocumentManagementSetRequest";
-export * from "./models/documentDataTypes";
+export * from "./models/api/IDocumentManagementUpdateRequest";
+export * from "./models/documentContexts";
+export * from "./models/documentTypes";
 export * from "./models/IDocument";
+export * from "./models/IDocumentAttestation";
 export * from "./models/IDocumentList";
 export * from "./models/IDocumentManagementComponent";

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

@@ -1,9 +1,10 @@
 import type { IAttestationInformation } from "@twin.org/attestation-models";
 import type { IBlobStorageEntry } from "@twin.org/blob-storage-models";
 import type { IJsonLdContextDefinitionElement, IJsonLdNodeObject } from "@twin.org/data-json-ld";
-import type { SchemaOrgTypes } from "@twin.org/standards-schema-org";
+import type { SchemaOrgContexts } from "@twin.org/standards-schema-org";
 import type { UneceDocumentCodes } from "@twin.org/standards-unece";
-import type { DocumentTypes } from "./documentDataTypes";
+import type { DocumentContexts } from "./documentContexts";
+import type { DocumentTypes } from "./documentTypes";
 /**
  * Interface describing a document.
  */
@@ -12,9 +13,9 @@ export interface IDocument {
      * JSON-LD Context.
      */
     "@context": [
-        typeof DocumentTypes.ContextRoot,
-        typeof DocumentTypes.ContextRootCommon,
-        typeof SchemaOrgTypes.ContextRoot,
+        typeof DocumentContexts.ContextRoot,
+        typeof DocumentContexts.ContextRootCommon,
+        typeof SchemaOrgContexts.ContextRoot,
         ...IJsonLdContextDefinitionElement[]
     ];
     /**
@@ -57,6 +58,10 @@ export interface IDocument {
      * The additional JSON-LD for blob storage if it was requested.
      */
     blobStorageEntry?: IBlobStorageEntry;
+    /**
+     * The data extracted from the document using data extraction services.
+     */
+    extractedData?: unknown;
     /**
      * The attestation for the document if one was created.
      */
@@ -78,11 +83,11 @@ export interface IDocument {
      */
     dateDeleted?: string;
     /**
-     * The previous revisions of the document.
+     * The node which added the document to the graph.
      */
-    revisions?: IDocument[];
+    nodeIdentity: string;
     /**
-     * The cursor to get the next chunk of revisions.
+     * The user who added the document to the graph.
      */
-    revisionCursor?: string;
+    userIdentity: string;
 }

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

@@ -0,0 +1,41 @@
+import type { SchemaOrgContexts } from "@twin.org/standards-schema-org";
+import type { UneceDocumentCodes } from "@twin.org/standards-unece";
+import type { DocumentContexts } from "./documentContexts";
+import type { DocumentTypes } from "./documentTypes";
+/**
+ * Interface describing a document attestation.
+ */
+export interface IDocumentAttestation {
+    /**
+     * JSON-LD Context.
+     */
+    "@context": [
+        typeof DocumentContexts.ContextRoot,
+        typeof DocumentContexts.ContextRootCommon,
+        typeof SchemaOrgContexts.ContextRoot
+    ];
+    /**
+     * JSON-LD Type.
+     */
+    type: typeof DocumentTypes.DocumentAttestation;
+    /**
+     * The id of the document.
+     */
+    documentId: string;
+    /**
+     * The code for the document type.
+     */
+    documentCode: UneceDocumentCodes;
+    /**
+     * The revision of the document as a 0 based index.
+     */
+    documentRevision: number;
+    /**
+     * The date/time of when the document was created.
+     */
+    dateCreated: string;
+    /**
+     * The hash of the document being attested.
+     */
+    blobHash: string;
+}

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

@@ -1,16 +1,17 @@
 import type { IJsonLdContextDefinitionElement } from "@twin.org/data-json-ld";
-import type { DocumentTypes } from "./documentDataTypes";
+import type { DocumentContexts } from "./documentContexts";
+import type { DocumentTypes } from "./documentTypes";
 import type { IDocument } from "./IDocument";
 /**
- * Interface describing a document entry list.
+ * Interface describing a list of document entries.
  */
 export interface IDocumentList {
     /**
      * JSON-LD Context.
      */
     "@context": [
-        typeof DocumentTypes.ContextRoot,
-        typeof DocumentTypes.ContextRootCommon,
+        typeof DocumentContexts.ContextRoot,
+        typeof DocumentContexts.ContextRootCommon,
         ...IJsonLdContextDefinitionElement[]
     ];
     /**
@@ -21,6 +22,10 @@ export interface IDocumentList {
      * The list of documents.
      */
     documents: IDocument[];
+    /**
+     * The ids of the other vertices which are connected to the document.
+     */
+    edges?: string[];
     /**
      * The cursor to get the next chunk of documents.
      */

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

@@ -1,78 +1,98 @@
+import type { IAuditableItemGraphVertexList } from "@twin.org/auditable-item-graph-models";
 import type { IComponent } from "@twin.org/core";
 import type { IJsonLdNodeObject } from "@twin.org/data-json-ld";
 import type { UneceDocumentCodes } from "@twin.org/standards-unece";
-import type { IDocument } from "./IDocument";
 import type { IDocumentList } from "./IDocumentList";
 /**
  * Interface describing an document management contract.
  */
 export interface IDocumentManagementComponent extends IComponent {
     /**
-     * Store a document in an auditable item graph vertex and add its content to blob storage.
+     * Create a document as an auditable item graph vertex and add its content to blob storage.
      * If the document id already exists and the blob data is different a new revision will be created.
      * For any other changes the current revision will be updated.
-     * @param auditableItemGraphId The auditable item graph vertex id to create the document on.
      * @param documentId The document id to create.
      * @param documentIdFormat The format of the document identifier.
      * @param documentCode The code for the document type.
      * @param blob The data to create the document with.
      * @param annotationObject Additional information to associate with the document.
-     * @param createAttestation Flag to create an attestation for the document, defaults to false.
+     * @param auditableItemGraphEdges The auditable item graph vertices to connect the document to.
+     * @param options Additional options for the set operation.
+     * @param options.createAttestation Flag to create an attestation for the document, defaults to false.
+     * @param options.addAlias Flag to add the document id as an alias to the aig vertex, defaults to true.
+     * @param options.aliasAnnotationObject Annotation object for the alias.
      * @param userIdentity The identity to perform the auditable item graph operation with.
      * @param nodeIdentity The node identity to use for vault operations.
-     * @returns The identifier for the document which includes the auditable item graph identifier.
+     * @returns The auditable item graph vertex created for the document including its revision.
      */
-    set(auditableItemGraphId: string, documentId: string, documentIdFormat: string | undefined, documentCode: UneceDocumentCodes, blob: Uint8Array, annotationObject?: IJsonLdNodeObject, createAttestation?: boolean, userIdentity?: string, nodeIdentity?: string): Promise<string>;
+    create(documentId: string, documentIdFormat: string | undefined, documentCode: UneceDocumentCodes, blob: Uint8Array, annotationObject?: IJsonLdNodeObject, auditableItemGraphEdges?: {
+        id: string;
+        addAlias?: boolean;
+        aliasAnnotationObject?: IJsonLdNodeObject;
+    }[], options?: {
+        createAttestation?: boolean;
+        addAlias?: boolean;
+        aliasAnnotationObject?: IJsonLdNodeObject;
+    }, userIdentity?: string, nodeIdentity?: string): Promise<string>;
     /**
-     * Get a specific document from an auditable item graph vertex.
-     * @param auditableItemGraphId The auditable item graph vertex id to get the document from.
-     * @param identifier The identifier of the document to get.
+     * Update a document as an auditable item graph vertex and add its content to blob storage.
+     * If the blob data is different a new revision will be created.
+     * For any other changes the current revision will be updated.
+     * @param auditableItemGraphDocumentId The auditable item graph vertex id which contains the document.
+     * @param blob The data to update the document with.
+     * @param annotationObject Additional information to associate with the document.
+     * @param auditableItemGraphEdges The auditable item graph vertices to connect the document to, if undefined retains current connections.
+     * @param userIdentity The identity to perform the auditable item graph operation with.
+     * @param nodeIdentity The node identity to use for vault operations.
+     * @returns Nothing.
+     */
+    update(auditableItemGraphDocumentId: string, blob?: Uint8Array, annotationObject?: IJsonLdNodeObject, auditableItemGraphEdges?: {
+        id: string;
+        addAlias?: boolean;
+        aliasAnnotationObject?: IJsonLdNodeObject;
+    }[], userIdentity?: string, nodeIdentity?: string): Promise<void>;
+    /**
+     * Get a document using it's auditable item graph vertex id and optional revision.
+     * @param auditableItemGraphDocumentId The auditable item graph vertex id which contains the document.
      * @param options Additional options for the get operation.
      * @param options.includeBlobStorageMetadata Flag to include the blob storage metadata for the document, defaults to false.
      * @param options.includeBlobStorageData Flag to include the blob storage data for the document, defaults to false.
      * @param options.includeAttestation Flag to include the attestation information for the document, defaults to false.
      * @param options.includeRemoved Flag to include deleted documents, defaults to false.
-     * @param options.maxRevisionCount Max number of revisions to return, defaults to 0.
-     * @param revisionCursor The cursor to get the next chunk of revisions.
+     * @param options.extractRuleGroupId If provided will extract data from the document using the specified rule group id.
+     * @param options.extractMimeType By default extraction will auto detect the mime type of the document, this can be used to override the detection.
+     * @param cursor The cursor to get the next chunk of revisions.
+     * @param pageSize Page size of items to return, defaults to 1 so only most recent is returned.
      * @param userIdentity The identity to perform the auditable item graph operation with.
      * @param nodeIdentity The node identity to use for vault operations.
      * @returns The documents and revisions if requested, ordered by revision descending, cursor is set if there are more document revisions.
      */
-    get(auditableItemGraphId: string, identifier: string, options?: {
+    get(auditableItemGraphDocumentId: string, options?: {
         includeBlobStorageMetadata?: boolean;
         includeBlobStorageData?: boolean;
         includeAttestation?: boolean;
         includeRemoved?: boolean;
-        maxRevisionCount?: number;
-    }, revisionCursor?: string, userIdentity?: string, nodeIdentity?: string): Promise<IDocument>;
+        extractRuleGroupId?: string;
+        extractMimeType?: string;
+    }, cursor?: string, pageSize?: number, userIdentity?: string, nodeIdentity?: string): Promise<IDocumentList>;
     /**
-     * Remove a specific document from an auditable item graph vertex.
-     * The documents dateDeleted will be set, but can still be queried with the includeRemoved flag.
-     * @param auditableItemGraphId The auditable item graph vertex id to remove the document from.
-     * @param identifier The identifier of the document to remove.
-     * @param options Additional options for the remove operation.
-     * @param options.removeAllRevisions Flag to remove all revisions of the document, defaults to false.
+     * Remove an auditable item graph vertex using it's id.
+     * The document dateDeleted will be set, but can still be queried with the includeRemoved flag.
+     * @param auditableItemGraphDocumentId The auditable item graph vertex id which contains the document.
+     * @param revision The revision of the document to remove.
      * @param userIdentity The identity to perform the auditable item graph operation with.
      * @param nodeIdentity The node identity to use for vault operations.
      * @returns Nothing.
      */
-    remove(auditableItemGraphId: string, identifier: string, options?: {
-        removeAllRevisions?: boolean;
-    }, userIdentity?: string, nodeIdentity?: string): Promise<void>;
+    removeRevision(auditableItemGraphDocumentId: string, revision: number, userIdentity?: string, nodeIdentity?: string): Promise<void>;
     /**
-     * Query an auditable item graph vertex for documents.
-     * @param auditableItemGraphId The auditable item graph vertex to get the documents from.
-     * @param documentCodes The document codes to query for, if undefined gets all document codes.
-     * @param options Additional options for the query operation.
-     * @param options.includeMostRecentRevisions Include the most recent 5 revisions, use the individual get to retrieve more.
-     * @param options.includeRemoved Flag to include deleted documents, defaults to false.
+     * Find all the document with a specific id.
+     * @param documentId The document id to find in the graph.
      * @param cursor The cursor to get the next chunk of documents.
+     * @param pageSize The page size to get the next chunk of documents.
      * @param userIdentity The identity to perform the auditable item graph operation with.
      * @param nodeIdentity The node identity to use for vault operations.
-     * @returns The most recent revisions of each document, cursor is set if there are more documents.
+     * @returns The graph vertices that contain documents referencing the specified document id.
      */
-    query(auditableItemGraphId: string, documentCodes?: UneceDocumentCodes[], options?: {
-        includeMostRecentRevisions?: boolean;
-        includeRemoved?: boolean;
-    }, cursor?: string, userIdentity?: string, nodeIdentity?: string): Promise<IDocumentList>;
+    query(documentId: string, cursor?: string, pageSize?: number, userIdentity?: string, nodeIdentity?: string): Promise<IAuditableItemGraphVertexList>;
 }

package/dist/types/models/api/{IDocumentManagementSetRequest.d.ts → IDocumentManagementCreateRequest.d.ts}

@@ -1,18 +1,9 @@
 import type { IJsonLdNodeObject } from "@twin.org/data-json-ld";
 import type { UneceDocumentCodes } from "@twin.org/standards-unece";
 /**
- * Request to set a document in an auditable item graph vertex.
+ * Request to create a document as an auditable item graph vertex.
  */
-export interface IDocumentManagementSetRequest {
-    /**
-     * The path parameters.
-     */
-    pathParams: {
-        /**
-         * The id of the auditable item graph vertex to store the document on.
-         */
-        auditableItemGraphId: string;
-    };
+export interface IDocumentManagementCreateRequest {
     /**
      * The body parameters.
      */
@@ -38,8 +29,24 @@ export interface IDocumentManagementSetRequest {
          */
         annotationObject?: IJsonLdNodeObject;
         /**
-         * Flag to create an attestation for the document, defaults to false
+         * The auditable item graph vertices to connect the document to.
+         */
+        auditableItemGraphEdges?: {
+            id: string;
+            addAlias?: boolean;
+            aliasAnnotationObject?: IJsonLdNodeObject;
+        }[];
+        /**
+         * Flag to create an attestation for the document, defaults to false.
          */
         createAttestation?: boolean;
+        /**
+         * Flag to add the document id as an alias to the aig vertex, defaults to true.
+         */
+        addAlias?: boolean;
+        /**
+         * Annotation object for the alias.
+         */
+        aliasAnnotationObject?: IJsonLdNodeObject;
     };
 }

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

@@ -13,14 +13,10 @@ export interface IDocumentManagementGetRequest {
      * The path parameters.
      */
     pathParams: {
-        /**
-         * The id of the auditable item graph vertex to store the document on.
-         */
-        auditableItemGraphId: string;
         /**
          * The full id of the document to get.
          */
-        documentId: string;
+        auditableItemGraphDocumentId: string;
     };
     /**
      * The query parameters.
@@ -47,13 +43,21 @@ export interface IDocumentManagementGetRequest {
          */
         includeRemoved?: boolean;
         /**
-         * Max number of revisions to return.
-         * @default 0
+         * If provided will extract data from the document using the specified rule group id.
+         */
+        extractRuleGroupId?: string;
+        /**
+         * By default extraction will auto detect the mime type of the document, this can be used to override the detection.
+         */
+        extractMimeType?: string;
+        /**
+         * Page size of items to return, defaults to 1 so only most recent is returned.
+         * @default 1
          */
-        maxRevisionCount?: number;
+        pageSize?: string;
         /**
          * The cursor to get the next chunk of revisions.
          */
-        revisionCursor?: string;
+        cursor?: string;
     };
 }

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

@@ -1,5 +1,5 @@
 import type { HeaderTypes, MimeTypes } from "@twin.org/web";
-import type { IDocument } from "../IDocument";
+import type { IDocumentList } from "../IDocumentList";
 /**
  * Response to get a document and optionally revisions from an auditable item graph vertex.
  */
@@ -13,5 +13,5 @@ export interface IDocumentManagementGetResponse {
     /**
      * The body parameters.
      */
-    body: IDocument;
+    body: IDocumentList;
 }

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

@@ -9,36 +9,21 @@ export interface IDocumentManagementQueryRequest {
     headers?: {
         [HeaderTypes.Accept]: typeof MimeTypes.Json | typeof MimeTypes.JsonLd;
     };
-    /**
-     * The path parameters.
-     */
-    pathParams: {
-        /**
-         * The id of the auditable item graph vertex which contains the documents.
-         */
-        auditableItemGraphId: string;
-    };
     /**
      * The query parameters.
      */
-    query?: {
+    query: {
         /**
-         * List of comma separated document codes to filter the query.
+         * The id of the document id we are trying to find.
          */
-        documentCodes?: string;
-        /**
-         * Include deleted documents in the response.
-         * @default false
-         */
-        includeRemoved?: boolean;
-        /**
-         * Include the most recent 5 revisions, use the individual get to retrieve more.
-         * @default false
-         */
-        includeMostRecentRevisions?: boolean;
+        documentId: string;
         /**
          * The cursor to get the next chunk of documents.
          */
         cursor?: string;
+        /**
+         * The number of documents to return.
+         */
+        pageSize?: string;
     };
 }

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

@@ -1,5 +1,5 @@
+import type { IAuditableItemGraphVertexList } from "@twin.org/auditable-item-graph-models";
 import type { HeaderTypes, MimeTypes } from "@twin.org/web";
-import type { IDocumentList } from "../IDocumentList";
 /**
  * Response to query the documents from an auditable item graph vertex.
  */
@@ -13,5 +13,5 @@ export interface IDocumentManagementQueryResponse {
     /**
      * The body parameters.
      */
-    body: IDocumentList;
+    body: IAuditableItemGraphVertexList;
 }

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

@@ -1,5 +1,5 @@
 /**
- * Request to remove a document from an auditable item graph.
+ * Request to remove a document revision from an auditable item graph.
  */
 export interface IDocumentManagementRemoveRequest {
     /**
@@ -7,22 +7,12 @@ export interface IDocumentManagementRemoveRequest {
      */
     pathParams: {
         /**
-         * The id of the auditable item graph vertex to remove the document from.
+         * The id of the auditable item graph vertex to remove the revision from.
          */
-        auditableItemGraphId: string;
+        auditableItemGraphDocumentId: string;
         /**
-         * The full id of the document to remove.
+         * The revision of the document to remove.
          */
-        documentId: string;
-    };
-    /**
-     * The query parameters.
-     */
-    query?: {
-        /**
-         * Flag to remove all revisions of the document.
-         * @default false
-         */
-        removeAllRevisions?: boolean;
+        revision: string;
     };
 }

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

@@ -0,0 +1,36 @@
+import type { IJsonLdNodeObject } from "@twin.org/data-json-ld";
+/**
+ * Request to update a document as an auditable item graph vertex.
+ */
+export interface IDocumentManagementUpdateRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The full id of the document to get.
+         */
+        auditableItemGraphDocumentId: string;
+    };
+    /**
+     * The body parameters.
+     */
+    body: {
+        /**
+         * The data to create the document with, in base64.
+         */
+        blob?: string;
+        /**
+         * Additional information to associate with the document.
+         */
+        annotationObject?: IJsonLdNodeObject;
+        /**
+         * The auditable item graph vertices to connect the document to.
+         */
+        auditableItemGraphEdges?: {
+            id: string;
+            addAlias?: boolean;
+            aliasAnnotationObject?: IJsonLdNodeObject;
+        }[];
+    };
+}

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

@@ -0,0 +1,17 @@
+/**
+ * The contexts of document management objects.
+ */
+export declare const DocumentContexts: {
+    /**
+     * The context root for the document types.
+     */
+    readonly ContextRoot: "https://schema.twindev.org/documents/";
+    /**
+     * The context root for the common types.
+     */
+    readonly ContextRootCommon: "https://schema.twindev.org/common/";
+};
+/**
+ * The contexts of document management objects.
+ */
+export type DocumentContexts = (typeof DocumentContexts)[keyof typeof DocumentContexts];

package/dist/types/models/{documentDataTypes.d.ts → documentTypes.d.ts}

@@ -2,18 +2,14 @@
  * The types of document management objects.
  */
 export declare const DocumentTypes: {
-    /**
-     * The context root for the document types.
-     */
-    readonly ContextRoot: "https://schema.twindev.org/documents/";
-    /**
-     * The context root for the common types.
-     */
-    readonly ContextRootCommon: "https://schema.twindev.org/common/";
     /**
      * Represents a document.
      */
     readonly Document: "Document";
+    /**
+     * Represents a document attestation.
+     */
+    readonly DocumentAttestation: "DocumentAttestation";
     /**
      * Represents a document list.
      */