@twin.org/auditable-item-graph-service 0.0.3-next.8 → 0.9.0-next.2

package/README.md

@@ -1,6 +1,8 @@
 # TWIN Auditable Item Graph Service
 
-Auditable Item Graph contract implementation and REST endpoint definitions.
+This package delivers the core graph operations, including create, update, query, and historical change retrieval with verifiable audit data.
+
+It also exposes route definitions so applications can host the service over HTTP while keeping behaviour aligned with shared contracts.
 
 ## Installation
 

package/dist/es/auditableItemGraphRoutes.js

@@ -1,7 +1,8 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-import { HttpParameterHelper } from "@twin.org/api-models";
+import { HttpContextIdKeys, HttpParameterHelper, HttpUrlHelper } from "@twin.org/api-models";
 import { AuditableItemGraphContexts, AuditableItemGraphTypes } from "@twin.org/auditable-item-graph-models";
+import { ContextIdStore } from "@twin.org/context";
 import { Coerce, ComponentFactory, Guards, Is } from "@twin.org/core";
 import { SchemaOrgContexts, SchemaOrgTypes } from "@twin.org/standards-schema-org";
 import { HeaderHelper, HeaderTypes, HttpStatusCode, MimeTypes } from "@twin.org/web";
@@ -39,6 +40,11 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
                     id: "auditableItemGraphCreateRequestExample",
                     request: {
                         body: {
+                            "@context": [
+                                AuditableItemGraphContexts.Context,
+                                AuditableItemGraphContexts.ContextCommon
+                            ],
+                            type: AuditableItemGraphTypes.Vertex,
                             annotationObject: {
                                 "@context": "https://schema.org",
                                 "@type": "Note",
@@ -46,6 +52,7 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
                             },
                             aliases: [
                                 {
+                                    type: AuditableItemGraphTypes.Alias,
                                     id: "bar456",
                                     annotationObject: {
                                         "@context": "https://schema.org",
@@ -54,6 +61,7 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
                                     }
                                 },
                                 {
+                                    type: AuditableItemGraphTypes.Alias,
                                     id: "foo321",
                                     annotationObject: {
                                         "@context": "https://schema.org",
@@ -64,6 +72,7 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
                             ],
                             resources: [
                                 {
+                                    type: AuditableItemGraphTypes.Resource,
                                     id: "resource1",
                                     resourceObject: {
                                         "@context": "https://schema.org",
@@ -72,6 +81,7 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
                                     }
                                 },
                                 {
+                                    type: AuditableItemGraphTypes.Resource,
                                     id: "resource2",
                                     resourceObject: {
                                         "@context": "https://schema.org",
@@ -82,6 +92,7 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
                             ],
                             edges: [
                                 {
+                                    type: AuditableItemGraphTypes.Edge,
                                     targetId: "aig:1234567890",
                                     edgeRelationships: ["frenemy"],
                                     annotationObject: {
@@ -91,6 +102,7 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
                                     }
                                 },
                                 {
+                                    type: AuditableItemGraphTypes.Edge,
                                     targetId: "aig:45678901234",
                                     edgeRelationships: ["end"],
                                     annotationObject: {
@@ -492,6 +504,114 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
             }
         ]
     };
+    const getVersionRoute = {
+        operationId: "auditableItemGraphVersionGet",
+        summary: "Get a graph vertex at a specific version",
+        tag: tagsAuditableItemGraph[0].name,
+        method: "GET",
+        path: `${baseRouteName}/:id/versions/:version`,
+        handler: async (httpRequestContext, request) => auditableItemGraphVersionGet(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IAuditableItemGraphVersionGetRequest",
+            examples: [
+                {
+                    id: "auditableItemGraphVersionGetRequestExample",
+                    request: {
+                        headers: {
+                            [HeaderTypes.Accept]: MimeTypes.Json
+                        },
+                        pathParams: {
+                            id: "aig:1234567890",
+                            version: "1"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "IAuditableItemGraphVersionGetResponse",
+                examples: [
+                    {
+                        id: "auditableItemGraphVersionGetResponseExample",
+                        response: {
+                            body: {
+                                "@context": [
+                                    AuditableItemGraphContexts.Context,
+                                    AuditableItemGraphContexts.ContextCommon,
+                                    SchemaOrgContexts.Context
+                                ],
+                                type: AuditableItemGraphTypes.Vertex,
+                                id: "aig:1234567890",
+                                dateCreated: "2024-08-22T11:55:16.271Z",
+                                version: 1
+                            }
+                        }
+                    }
+                ]
+            }
+        ]
+    };
+    const getVersionListRoute = {
+        operationId: "auditableItemGraphVersionList",
+        summary: "Get all versions of a graph vertex",
+        tag: tagsAuditableItemGraph[0].name,
+        method: "GET",
+        path: `${baseRouteName}/:id/versions`,
+        handler: async (httpRequestContext, request) => auditableItemGraphVersionList(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IAuditableItemGraphVersionListRequest",
+            examples: [
+                {
+                    id: "auditableItemGraphVersionListRequestExample",
+                    request: {
+                        headers: {
+                            [HeaderTypes.Accept]: MimeTypes.Json
+                        },
+                        pathParams: {
+                            id: "aig:1234567890"
+                        }
+                    }
+                },
+                {
+                    id: "auditableItemGraphVersionListAfterRequestExample",
+                    request: {
+                        pathParams: {
+                            id: "aig:1234567890"
+                        },
+                        query: {
+                            after: "2026-04-03T12:00:00Z"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "IAuditableItemGraphVersionListResponse",
+                examples: [
+                    {
+                        id: "auditableItemGraphVersionListResponseExample",
+                        response: {
+                            body: {
+                                "@context": [
+                                    SchemaOrgContexts.Context,
+                                    AuditableItemGraphContexts.Context,
+                                    AuditableItemGraphContexts.ContextCommon
+                                ],
+                                type: [SchemaOrgTypes.ItemList, AuditableItemGraphTypes.VertexVersionList],
+                                [SchemaOrgTypes.ItemListElement]: [
+                                    { version: 0, dateCreated: "2024-08-22T11:55:16.271Z" },
+                                    { version: 1, dateCreated: "2024-08-22T11:56:00.000Z" },
+                                    { version: 2, dateCreated: "2024-08-22T11:57:00.000Z" }
+                                ]
+                            }
+                        }
+                    }
+                ]
+            }
+        ]
+    };
     const updateRoute = {
         operationId: "auditableItemGraphUpdate",
         summary: "Update a graph vertex",
@@ -509,6 +629,11 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
                             id: "aig:1234567890"
                         },
                         body: {
+                            "@context": [
+                                AuditableItemGraphContexts.Context,
+                                AuditableItemGraphContexts.ContextCommon
+                            ],
+                            type: AuditableItemGraphTypes.Vertex,
                             annotationObject: {
                                 "@context": "https://schema.org",
                                 "@type": "Note",
@@ -516,6 +641,7 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
                             },
                             aliases: [
                                 {
+                                    type: AuditableItemGraphTypes.Alias,
                                     id: "bar456",
                                     annotationObject: {
                                         "@context": "https://schema.org",
@@ -524,6 +650,7 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
                                     }
                                 },
                                 {
+                                    type: AuditableItemGraphTypes.Alias,
                                     id: "foo321",
                                     annotationObject: {
                                         "@context": "https://schema.org",
@@ -534,6 +661,7 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
                             ],
                             resources: [
                                 {
+                                    type: AuditableItemGraphTypes.Resource,
                                     id: "resource1",
                                     resourceObject: {
                                         "@context": "https://schema.org",
@@ -542,6 +670,7 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
                                     }
                                 },
                                 {
+                                    type: AuditableItemGraphTypes.Resource,
                                     id: "resource2",
                                     resourceObject: {
                                         "@context": "https://schema.org",
@@ -552,6 +681,7 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
                             ],
                             edges: [
                                 {
+                                    type: AuditableItemGraphTypes.Edge,
                                     id: "edge1",
                                     targetId: "aig:1234567890",
                                     edgeRelationships: ["frenemy"],
@@ -562,6 +692,7 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
                                     }
                                 },
                                 {
+                                    type: AuditableItemGraphTypes.Edge,
                                     id: "edge2",
                                     targetId: "aig:45678901234",
                                     edgeRelationships: ["end"],
@@ -583,6 +714,47 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
             }
         ]
     };
+    const updatePartialRoute = {
+        operationId: "auditableItemGraphUpdatePartial",
+        summary: "Partially update a graph vertex",
+        tag: tagsAuditableItemGraph[0].name,
+        method: "PATCH",
+        path: `${baseRouteName}/:id`,
+        handler: async (httpRequestContext, request) => auditableItemGraphUpdatePartial(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IAuditableItemGraphUpdatePartialRequest",
+            examples: [
+                {
+                    id: "auditableItemGraphUpdatePartialRequestExample",
+                    request: {
+                        pathParams: {
+                            id: "aig:1234567890"
+                        },
+                        body: {
+                            "@context": [
+                                AuditableItemGraphContexts.Context,
+                                AuditableItemGraphContexts.ContextCommon
+                            ],
+                            edgePatches: {
+                                add: [
+                                    {
+                                        type: AuditableItemGraphTypes.Edge,
+                                        targetId: "aig:45678901234",
+                                        edgeRelationships: ["document"]
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "INoContentResponse"
+            }
+        ]
+    };
     const listRoute = {
         operationId: "auditableItemGraphList",
         summary: "Query graph vertices by id or alias",
@@ -698,7 +870,52 @@ export function generateRestRoutesAuditableItemGraph(baseRouteName, componentNam
             }
         ]
     };
-    return [createRoute, getRoute, getChangesetRoute, getChangesetListRoute, updateRoute, listRoute];
+    const removeProofRoute = {
+        operationId: "auditableItemGraphRemoveProof",
+        summary: "Remove the notarization proof from all changesets of a graph vertex",
+        tag: tagsAuditableItemGraph[0].name,
+        method: "DELETE",
+        path: `${baseRouteName}/:id/proof`,
+        handler: async (httpRequestContext, request) => auditableItemGraphRemoveProof(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IAuditableItemGraphRemoveProofRequest",
+            examples: [
+                {
+                    id: "auditableItemGraphRemoveProofRequestExample",
+                    request: {
+                        pathParams: {
+                            id: "0101010101010101010101010101010101010101010101010101010101010101"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "INoContentResponse",
+                examples: [
+                    {
+                        id: "auditableItemGraphRemoveProofResponseExample",
+                        response: {
+                            statusCode: HttpStatusCode.noContent
+                        }
+                    }
+                ]
+            }
+        ]
+    };
+    return [
+        createRoute,
+        getRoute,
+        getVersionRoute,
+        getVersionListRoute,
+        getChangesetRoute,
+        getChangesetListRoute,
+        updateRoute,
+        updatePartialRoute,
+        listRoute,
+        removeProofRoute
+    ];
 }
 /**
  * Create the graph vertex.
@@ -762,9 +979,9 @@ export async function auditableItemGraphChangesetList(httpRequestContext, compon
     const headers = {
         [HeaderTypes.ContentType]: request.headers?.[HeaderTypes.Accept] === MimeTypes.JsonLd ? MimeTypes.JsonLd : MimeTypes.Json
     };
-    const hostingComponent = ComponentFactory.get(httpRequestContext.hostingComponentType ?? "hosting");
     if (Is.stringValue(result.cursor)) {
-        headers[HeaderTypes.Link] = HeaderHelper.createLinkHeader(await hostingComponent.buildPublicUrl(httpRequestContext.serverRequest.url), { cursor: result.cursor }, "next");
+        const contextIds = await ContextIdStore.getContextIds();
+        headers[HeaderTypes.Link] = HeaderHelper.createLinkHeader(HttpUrlHelper.replaceOrigin(httpRequestContext.serverRequest.url, contextIds?.[HttpContextIdKeys.PublicOrigin]), { cursor: result.cursor }, "next");
     }
     return {
         headers,
@@ -783,7 +1000,7 @@ export async function auditableItemGraphChangesetGet(httpRequestContext, compone
     Guards.object(ROUTES_SOURCE, "request.pathParams", request.pathParams);
     Guards.stringValue(ROUTES_SOURCE, "request.pathParams.id", request.pathParams.id);
     const component = ComponentFactory.get(componentName);
-    const changesetUrn = `aig:${request.pathParams.id}:changeset:${request.pathParams.changesetId}`;
+    const changesetUrn = `${request.pathParams.id}:changeset:${request.pathParams.changesetId}`;
     const result = await component.getChangeset(changesetUrn, {
         verifySignatureDepth: request.query?.verifySignatureDepth
     });
@@ -797,7 +1014,7 @@ export async function auditableItemGraphChangesetGet(httpRequestContext, compone
     };
 }
 /**
- * Update the graph vertex.
+ * Update the graph vertex (PUT — full replacement of vertex state).
  * @param httpRequestContext The request context for the API.
  * @param componentName The name of the component to use in the routes.
  * @param request The request.
@@ -814,6 +1031,24 @@ export async function auditableItemGraphUpdate(httpRequestContext, componentName
         statusCode: HttpStatusCode.noContent
     };
 }
+/**
+ * Partially update the graph vertex (PATCH — optional scalars; list fields use `{ add, remove }`).
+ * @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 auditableItemGraphUpdatePartial(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.pathParams", request.pathParams);
+    Guards.stringValue(ROUTES_SOURCE, "request.pathParams.id", request.pathParams.id);
+    Guards.object(ROUTES_SOURCE, "request.body", request.body);
+    const component = ComponentFactory.get(componentName);
+    await component.updatePartial({ ...request.body, id: request.pathParams.id });
+    return {
+        statusCode: HttpStatusCode.noContent
+    };
+}
 /**
  * Query the graph vertices.
  * @param httpRequestContext The request context for the API.
@@ -824,7 +1059,6 @@ export async function auditableItemGraphUpdate(httpRequestContext, componentName
 export async function auditableItemGraphList(httpRequestContext, componentName, request) {
     Guards.object(ROUTES_SOURCE, "request", request);
     Guards.object(ROUTES_SOURCE, "request.query", request.query);
-    const hostingComponent = ComponentFactory.get(httpRequestContext.hostingComponentType ?? "hosting");
     const component = ComponentFactory.get(componentName);
     const result = await component.query({
         id: request.query?.id,
@@ -836,11 +1070,78 @@ export async function auditableItemGraphList(httpRequestContext, componentName,
         [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");
+        const contextIds = await ContextIdStore.getContextIds();
+        headers[HeaderTypes.Link] = HeaderHelper.createLinkHeader(HttpUrlHelper.replaceOrigin(httpRequestContext.serverRequest.url, contextIds?.[HttpContextIdKeys.PublicOrigin]), { cursor: result.cursor }, "next");
     }
     return {
         headers,
         body: result.entries
     };
 }
+/**
+ * Get the graph vertex at a specific version.
+ * @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 auditableItemGraphVersionGet(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.pathParams", request.pathParams);
+    Guards.stringValue(ROUTES_SOURCE, "request.pathParams.id", request.pathParams.id);
+    const version = Coerce.integer(request.pathParams.version);
+    Guards.integer(ROUTES_SOURCE, "request.pathParams.version", version);
+    const component = ComponentFactory.get(componentName);
+    const result = await component.getVersion(request.pathParams.id, version);
+    return {
+        headers: {
+            [HeaderTypes.ContentType]: request.headers?.[HeaderTypes.Accept] === MimeTypes.JsonLd
+                ? MimeTypes.JsonLd
+                : MimeTypes.Json
+        },
+        body: result
+    };
+}
+/**
+ * Remove the notarization proof from all changesets of a 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 auditableItemGraphRemoveProof(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", 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.removeProof(request.pathParams.id);
+    return {
+        statusCode: HttpStatusCode.noContent
+    };
+}
+/**
+ * Get all versions of a 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 auditableItemGraphVersionList(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.pathParams", request.pathParams);
+    Guards.stringValue(ROUTES_SOURCE, "request.pathParams.id", request.pathParams.id);
+    const component = ComponentFactory.get(componentName);
+    const result = await component.getVersions(request.pathParams.id, {
+        after: request.query?.after,
+        before: request.query?.before
+    });
+    return {
+        headers: {
+            [HeaderTypes.ContentType]: request.headers?.[HeaderTypes.Accept] === MimeTypes.JsonLd
+                ? MimeTypes.JsonLd
+                : MimeTypes.Json
+        },
+        body: result
+    };
+}
 //# sourceMappingURL=auditableItemGraphRoutes.js.map