@twin.org/document-management-service 0.0.2-next.4 → 0.0.3-next.10

package/dist/es/documentManagementRoutes.js

@@ -0,0 +1,593 @@
+import { AuditableItemGraphContexts, AuditableItemGraphTypes } from "@twin.org/auditable-item-graph-models";
+import { Coerce, ComponentFactory, Converter, Guards, Is } from "@twin.org/core";
+import { DocumentContexts, DocumentTypes } from "@twin.org/document-management-models";
+import { SchemaOrgContexts, SchemaOrgTypes } from "@twin.org/standards-schema-org";
+import { UneceDocumentCodeList } from "@twin.org/standards-unece";
+import { HeaderHelper, HeaderTypes, HttpStatusCode, MimeTypes } from "@twin.org/web";
+/**
+ * The source used when communicating about these routes.
+ */
+const ROUTES_SOURCE = "documentManagementStorageRoutes";
+/**
+ * The tag to associate with the routes.
+ */
+export const tagsDocumentManagement = [
+    {
+        name: "Document Management",
+        description: "Endpoints which are modelled to access a document management contract."
+    }
+];
+/**
+ * The REST routes for document management.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+export function generateRestRoutesDocumentManagement(baseRouteName, componentName) {
+    const documentManagementCreateRoute = {
+        operationId: "DocumentManagementSet",
+        summary: "Store a document in an auditable item graph vertex and add its content to blob storage.",
+        tag: tagsDocumentManagement[0].name,
+        method: "POST",
+        path: `${baseRouteName}/`,
+        handler: async (httpRequestContext, request) => documentManagementCreate(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IDocumentManagementCreateRequest",
+            examples: [
+                {
+                    id: "DocumentManagementCreateRequestExample",
+                    request: {
+                        body: {
+                            documentId: "2721000",
+                            documentIdFormat: "bol",
+                            documentCode: UneceDocumentCodeList.BillOfLading,
+                            blob: "SGVsbG8gV29ybGQ=",
+                            annotationObject: {
+                                "@context": "https://schema.org",
+                                "@type": "DigitalDocument",
+                                name: "myfile.pdf"
+                            },
+                            createAttestation: true
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "ICreatedResponse",
+                examples: [
+                    {
+                        id: "DocumentManagementCreateResponseExample",
+                        response: {
+                            statusCode: HttpStatusCode.created,
+                            headers: {
+                                [HeaderTypes.Location]: "aig%3A123456"
+                            }
+                        }
+                    }
+                ]
+            }
+        ]
+    };
+    const documentManagementUpdateRoute = {
+        operationId: "DocumentManagementUpdate",
+        summary: "Update a document in an auditable item graph vertex and add its content to blob storage.",
+        tag: tagsDocumentManagement[0].name,
+        method: "PUT",
+        path: `${baseRouteName}/:auditableItemGraphDocumentId`,
+        handler: async (httpRequestContext, request) => documentManagementUpdate(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IDocumentManagementUpdateRequest",
+            examples: [
+                {
+                    id: "DocumentManagementUpdateRequestExample",
+                    request: {
+                        pathParams: {
+                            auditableItemGraphDocumentId: "aig:123456"
+                        },
+                        body: {
+                            blob: "SGVsbG8gV29ybGQ=",
+                            annotationObject: {
+                                "@context": "https://schema.org",
+                                "@type": "DigitalDocument",
+                                name: "myfile.pdf"
+                            }
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "INoContentResponse",
+                examples: [
+                    {
+                        id: "DocumentManagementCreateResponseExample",
+                        response: {
+                            statusCode: HttpStatusCode.noContent
+                        }
+                    }
+                ]
+            }
+        ]
+    };
+    const documentManagementGetRoute = {
+        operationId: "DocumentManagementGet",
+        summary: "Get the data for a document from document management",
+        tag: tagsDocumentManagement[0].name,
+        method: "GET",
+        path: `${baseRouteName}/:auditableItemGraphDocumentId`,
+        handler: async (httpRequestContext, request) => documentManagementGet(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IDocumentManagementGetRequest",
+            examples: [
+                {
+                    id: "DocumentManagementGetRequestExample",
+                    request: {
+                        pathParams: {
+                            auditableItemGraphDocumentId: "aig:123456"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "IDocumentManagementGetResponse",
+                examples: [
+                    {
+                        id: "DocumentManagementGetResponseExample",
+                        response: {
+                            body: {
+                                "@context": [
+                                    SchemaOrgContexts.Context,
+                                    DocumentContexts.Context,
+                                    DocumentContexts.ContextCommon
+                                ],
+                                type: SchemaOrgTypes.ItemList,
+                                [SchemaOrgTypes.ItemListElement]: [
+                                    {
+                                        "@context": [
+                                            SchemaOrgContexts.Context,
+                                            DocumentContexts.Context,
+                                            DocumentContexts.ContextCommon
+                                        ],
+                                        type: DocumentTypes.Document,
+                                        id: "2721000:0",
+                                        documentId: "2721000",
+                                        documentIdFormat: "bol",
+                                        documentCode: UneceDocumentCodeList.BillOfLading,
+                                        documentRevision: 0,
+                                        blobStorageId: "blob-memory:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70",
+                                        integrity: "sha256-123456",
+                                        dateCreated: "2024-01-01T00:00:00Z",
+                                        annotationObject: {
+                                            "@context": "https://schema.org",
+                                            "@type": "DigitalDocument",
+                                            name: "myfile.pdf"
+                                        },
+                                        organizationIdentity: "did:entity-storage:0x6363636363636363636363636363636363636363636363636363636363636363",
+                                        userIdentity: "did:entity-storage:0x6363636363636363636363636363636363636363636363636363636363636363"
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                ]
+            },
+            {
+                type: "IDocumentManagementGetResponse",
+                mimeType: MimeTypes.JsonLd,
+                examples: [
+                    {
+                        id: "DocumentManagementGetResponseExample",
+                        response: {
+                            body: {
+                                "@context": [
+                                    SchemaOrgContexts.Context,
+                                    DocumentContexts.Context,
+                                    DocumentContexts.ContextCommon
+                                ],
+                                type: SchemaOrgTypes.ItemList,
+                                [SchemaOrgTypes.ItemListElement]: [
+                                    {
+                                        "@context": [
+                                            SchemaOrgContexts.Context,
+                                            DocumentContexts.Context,
+                                            DocumentContexts.ContextCommon
+                                        ],
+                                        type: DocumentTypes.Document,
+                                        id: "2721000:0",
+                                        documentId: "2721000",
+                                        documentIdFormat: "bol",
+                                        documentCode: UneceDocumentCodeList.BillOfLading,
+                                        documentRevision: 0,
+                                        blobStorageId: "blob-memory:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70",
+                                        integrity: "sha256-123456",
+                                        dateCreated: "2024-01-01T00:00:00Z",
+                                        annotationObject: {
+                                            "@context": "https://schema.org",
+                                            "@type": "DigitalDocument",
+                                            name: "myfile.pdf"
+                                        },
+                                        organizationIdentity: "did:entity-storage:0x6363636363636363636363636363636363636363636363636363636363636363",
+                                        userIdentity: "did:entity-storage:0x6363636363636363636363636363636363636363636363636363636363636363"
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                ]
+            },
+            {
+                type: "INotFoundResponse"
+            }
+        ]
+    };
+    const documentManagementGetRevisionRoute = {
+        operationId: "DocumentManagementGetRevision",
+        summary: "Get the data for a document revision from document management",
+        tag: tagsDocumentManagement[0].name,
+        method: "GET",
+        path: `${baseRouteName}/:auditableItemGraphDocumentId/:revision`,
+        handler: async (httpRequestContext, request) => documentManagementGetRevision(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IDocumentManagementGetRequest",
+            examples: [
+                {
+                    id: "DocumentManagementGetRevisionRequestExample",
+                    request: {
+                        pathParams: {
+                            auditableItemGraphDocumentId: "aig:123456",
+                            revision: "1"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "IDocumentManagementGetRevisionResponse",
+                examples: [
+                    {
+                        id: "DocumentManagementGetRevisionResponseExample",
+                        response: {
+                            body: {
+                                "@context": [
+                                    SchemaOrgContexts.Context,
+                                    DocumentContexts.Context,
+                                    DocumentContexts.ContextCommon
+                                ],
+                                type: DocumentTypes.Document,
+                                id: "2721000:0",
+                                documentId: "2721000",
+                                documentIdFormat: "bol",
+                                documentCode: UneceDocumentCodeList.BillOfLading,
+                                documentRevision: 1,
+                                blobStorageId: "blob-memory:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70",
+                                integrity: "sha256-123456",
+                                dateCreated: "2024-01-01T00:00:00Z",
+                                annotationObject: {
+                                    "@context": "https://schema.org",
+                                    "@type": "DigitalDocument",
+                                    name: "myfile.pdf"
+                                },
+                                organizationIdentity: "did:entity-storage:0x6363636363636363636363636363636363636363636363636363636363636363",
+                                userIdentity: "did:entity-storage:0x6363636363636363636363636363636363636363636363636363636363636363"
+                            }
+                        }
+                    }
+                ]
+            },
+            {
+                type: "IDocumentManagementGetRevisionResponse",
+                mimeType: MimeTypes.JsonLd,
+                examples: [
+                    {
+                        id: "DocumentManagementGetRevisionResponseExample",
+                        response: {
+                            body: {
+                                "@context": [
+                                    SchemaOrgContexts.Context,
+                                    DocumentContexts.Context,
+                                    DocumentContexts.ContextCommon
+                                ],
+                                type: DocumentTypes.Document,
+                                id: "2721000:0",
+                                documentId: "2721000",
+                                documentIdFormat: "bol",
+                                documentCode: UneceDocumentCodeList.BillOfLading,
+                                documentRevision: 1,
+                                blobStorageId: "blob-memory:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70",
+                                integrity: "sha256-123456",
+                                dateCreated: "2024-01-01T00:00:00Z",
+                                annotationObject: {
+                                    "@context": "https://schema.org",
+                                    "@type": "DigitalDocument",
+                                    name: "myfile.pdf"
+                                },
+                                organizationIdentity: "did:entity-storage:0x6363636363636363636363636363636363636363636363636363636363636363",
+                                userIdentity: "did:entity-storage:0x6363636363636363636363636363636363636363636363636363636363636363"
+                            }
+                        }
+                    }
+                ]
+            },
+            {
+                type: "INotFoundResponse"
+            }
+        ]
+    };
+    const documentManagementRemoveRevisionRoute = {
+        operationId: "DocumentManagementRemove",
+        summary: "Remove an document from an auditable item graph vertex",
+        tag: tagsDocumentManagement[0].name,
+        method: "DELETE",
+        path: `${baseRouteName}/:auditableItemGraphDocumentId/:revision`,
+        handler: async (httpRequestContext, request) => documentManagementRemove(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IDocumentManagementRemoveRequest",
+            examples: [
+                {
+                    id: "DocumentManagementRemoveRequestExample",
+                    request: {
+                        pathParams: {
+                            auditableItemGraphDocumentId: "aig:1234",
+                            revision: "1"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "INoContentResponse"
+            },
+            {
+                type: "INotFoundResponse"
+            }
+        ]
+    };
+    const documentManagementQueryRoute = {
+        operationId: "DocumentManagementQuery",
+        summary: "Query the items from an auditable item graph vertex",
+        tag: tagsDocumentManagement[0].name,
+        method: "GET",
+        path: `${baseRouteName}/`,
+        handler: async (httpRequestContext, request) => documentManagementQuery(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IDocumentManagementQueryRequest",
+            examples: [
+                {
+                    id: "DocumentManagementQueryRequestExample",
+                    request: {
+                        query: {
+                            documentId: "2721000"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "IDocumentManagementQueryResponse",
+                examples: [
+                    {
+                        id: "DocumentManagementQueryResponseExample",
+                        response: {
+                            body: {
+                                "@context": [SchemaOrgContexts.Context, AuditableItemGraphContexts.Context],
+                                type: [SchemaOrgTypes.ItemList, AuditableItemGraphTypes.VertexList],
+                                [SchemaOrgTypes.ItemListElement]: [
+                                    {
+                                        "@context": [
+                                            AuditableItemGraphContexts.Context,
+                                            AuditableItemGraphContexts.ContextCommon
+                                        ],
+                                        id: "aig:c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7c7",
+                                        type: AuditableItemGraphTypes.Vertex,
+                                        dateCreated: "2024-08-22T04:13:20.000Z",
+                                        aliases: [
+                                            {
+                                                "@context": [AuditableItemGraphContexts.Context],
+                                                id: "test-id-0",
+                                                type: AuditableItemGraphTypes.Alias,
+                                                dateCreated: "2024-08-22T04:13:20.000Z"
+                                            }
+                                        ],
+                                        resources: [
+                                            {
+                                                "@context": AuditableItemGraphContexts.Context,
+                                                type: AuditableItemGraphTypes.Resource,
+                                                dateCreated: "2024-08-22T04:13:20.000Z",
+                                                resourceObject: {
+                                                    "@context": [
+                                                        "https://schema.twindev.org/documents/",
+                                                        "https://schema.twindev.org/common/",
+                                                        "https://schema.org"
+                                                    ],
+                                                    type: "Document",
+                                                    id: "test-id-0:0",
+                                                    documentId: "test-id-0",
+                                                    documentCode: "unece:DocumentCodeList#705",
+                                                    documentRevision: 0,
+                                                    annotationObject: {
+                                                        "@context": "https://schema.org",
+                                                        type: "DigitalDocument",
+                                                        name: "bill-of-lading"
+                                                    },
+                                                    integrity: "sha256-E3Duqrp6bHojSx+CzDttAToAiP1eFkCDAPBbKLABVGM=",
+                                                    blobStorageId: "blob:memory:1370eeaaba7a6c7a234b1f82cc3b6d013a0088fd5e16408300f05b28b0015463",
+                                                    dateCreated: "2024-08-22T04:13:20.000Z",
+                                                    organizationIdentity: "did:entity-storage:0x0101010101010101010101010101010101010101010101010101010101010101",
+                                                    userIdentity: "did:entity-storage:0x0404040404040404040404040404040404040404040404040404040404040404"
+                                                }
+                                            }
+                                        ]
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                ]
+            }
+        ]
+    };
+    return [
+        documentManagementCreateRoute,
+        documentManagementUpdateRoute,
+        documentManagementGetRoute,
+        documentManagementGetRevisionRoute,
+        documentManagementRemoveRevisionRoute,
+        documentManagementQueryRoute
+    ];
+}
+/**
+ * Create a document as an auditable item graph vertex.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export async function documentManagementCreate(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", 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.documentId, request.body.documentIdFormat, request.body.documentCode, Converter.base64ToBytes(request.body.blob), request.body.annotationObject, request.body.auditableItemGraphEdges, {
+        createAttestation: request.body.createAttestation,
+        addAlias: request.body.addAlias,
+        aliasAnnotationObject: request.body.aliasAnnotationObject
+    });
+    return {
+        statusCode: HttpStatusCode.created,
+        headers: {
+            location: id
+        }
+    };
+}
+/**
+ * Get the document from the auditable item graph vertex.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export async function documentManagementGet(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.pathParams", request.pathParams);
+    Guards.stringValue(ROUTES_SOURCE, "request.pathParams.auditableItemGraphDocumentId", request.pathParams.auditableItemGraphDocumentId);
+    const hostingComponent = ComponentFactory.get(httpRequestContext.hostingComponentType ?? "hosting");
+    const component = ComponentFactory.get(componentName);
+    const result = await component.get(request.pathParams.auditableItemGraphDocumentId, {
+        includeBlobStorageMetadata: Coerce.boolean(request.query?.includeBlobStorageMetadata),
+        includeBlobStorageData: Coerce.boolean(request.query?.includeBlobStorageData),
+        includeAttestation: Coerce.boolean(request.query?.includeAttestation),
+        includeRemoved: Coerce.boolean(request.query?.includeRemoved),
+        extractRuleGroupId: request.query?.extractRuleGroupId,
+        extractMimeType: request.query?.extractMimeType
+    }, request.query?.cursor, Coerce.integer(request.query?.limit));
+    const headers = {
+        [HeaderTypes.ContentType]: request.headers?.[HeaderTypes.Accept] === MimeTypes.JsonLd ? MimeTypes.JsonLd : MimeTypes.Json
+    };
+    if (Is.stringValue(result.cursor)) {
+        headers[HeaderTypes.Link] = HeaderHelper.createLinkHeader(await hostingComponent.buildPublicUrl(httpRequestContext.serverRequest.url), { cursor: result.cursor }, "next");
+    }
+    return {
+        headers,
+        body: result.entries
+    };
+}
+/**
+ * Get the document revision from the auditable item graph vertex.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export async function documentManagementGetRevision(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.pathParams", request.pathParams);
+    Guards.stringValue(ROUTES_SOURCE, "request.pathParams.auditableItemGraphDocumentId", request.pathParams.auditableItemGraphDocumentId);
+    const revision = Coerce.integer(request.pathParams.revision);
+    Guards.integer(ROUTES_SOURCE, "revision", revision);
+    const component = ComponentFactory.get(componentName);
+    const result = await component.getRevision(request.pathParams.auditableItemGraphDocumentId, revision, {
+        includeBlobStorageMetadata: Coerce.boolean(request.query?.includeBlobStorageMetadata),
+        includeBlobStorageData: Coerce.boolean(request.query?.includeBlobStorageData),
+        includeAttestation: Coerce.boolean(request.query?.includeAttestation),
+        extractRuleGroupId: request.query?.extractRuleGroupId,
+        extractMimeType: request.query?.extractMimeType
+    });
+    return {
+        headers: {
+            [HeaderTypes.ContentType]: request.headers?.[HeaderTypes.Accept] === MimeTypes.JsonLd
+                ? MimeTypes.JsonLd
+                : MimeTypes.Json
+        },
+        body: result
+    };
+}
+/**
+ * Update the document from the auditable item graph vertex.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export async function documentManagementUpdate(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.pathParams", request.pathParams);
+    Guards.stringValue(ROUTES_SOURCE, "request.pathParams.auditableItemGraphDocumentId", request.pathParams.auditableItemGraphDocumentId);
+    const component = ComponentFactory.get(componentName);
+    await component.update(request.pathParams.auditableItemGraphDocumentId, Is.stringValue(request.body.blob) ? Converter.base64ToBytes(request.body.blob) : undefined, request.body.annotationObject, request.body.auditableItemGraphEdges);
+    return {
+        statusCode: HttpStatusCode.noContent
+    };
+}
+/**
+ * Remove the document from the auditable item graph vertex.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export async function documentManagementRemove(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.pathParams", request.pathParams);
+    Guards.stringValue(ROUTES_SOURCE, "request.pathParams.auditableItemGraphDocumentId", request.pathParams.auditableItemGraphDocumentId);
+    const revision = Coerce.number(request.pathParams.revision);
+    Guards.integer(ROUTES_SOURCE, "request.pathParams.revision", revision);
+    const component = ComponentFactory.get(componentName);
+    await component.removeRevision(request.pathParams.auditableItemGraphDocumentId, revision);
+    return {
+        statusCode: HttpStatusCode.noContent
+    };
+}
+/**
+ * Query the documents from an auditable item graph vertex.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export async function documentManagementQuery(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.query", request.query);
+    Guards.stringValue(ROUTES_SOURCE, "request.query.documentId", request.query.documentId);
+    const hostingComponent = ComponentFactory.get(httpRequestContext.hostingComponentType ?? "hosting");
+    const component = ComponentFactory.get(componentName);
+    const result = await component.query(request.query.documentId, request.query?.cursor, Coerce.integer(request.query?.limit));
+    const headers = {
+        [HeaderTypes.ContentType]: request.headers?.[HeaderTypes.Accept] === MimeTypes.JsonLd ? MimeTypes.JsonLd : MimeTypes.Json
+    };
+    if (Is.stringValue(result.cursor)) {
+        headers[HeaderTypes.Link] = HeaderHelper.createLinkHeader(await hostingComponent.buildPublicUrl(httpRequestContext.serverRequest.url), { cursor: result.cursor }, "next");
+    }
+    return {
+        headers,
+        body: result.entries
+    };
+}
+//# sourceMappingURL=documentManagementRoutes.js.map