@twin.org/auditable-item-graph-service 0.0.3-next.13 → 0.0.3-next.15

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

@@ -27,4 +27,8 @@ export declare class AuditableItemGraphChangeset {
      * The immutable proof id which contains the signature for this changeset.
      */
     proofId?: string;
+    /**
+     * The version number of the vertex after this changeset was applied.
+     */
+    version?: number;
 }

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

@@ -46,4 +46,8 @@ export declare class AuditableItemGraphVertex {
      * Edges connected to the vertex.
      */
     edges?: AuditableItemGraphEdge[];
+    /**
+     * The current version of the vertex, incremented on each changeset.
+     */
+    version?: number;
 }

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

@@ -22,6 +22,10 @@ export interface IAuditableItemGraphServiceConstructorOptions {
      * The event bus component type, defaults to no event bus.
      */
     eventBusComponentType?: string;
+    /**
+     * The component type for the optional telemetry component used for event metrics, defaults to no telemetry.
+     */
+    telemetryComponentType?: string;
     /**
      * The configuration for the service.
      */

package/docs/changelog.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.0.3-next.15](https://github.com/iotaledger/twin-auditable-item-graph/compare/auditable-item-graph-service-v0.0.3-next.14...auditable-item-graph-service-v0.0.3-next.15) (2026-05-20)
+
+
+### Features
+
+* add event-driven telemetry metrics ([#63](https://github.com/iotaledger/twin-auditable-item-graph/issues/63)) ([8fe6cdd](https://github.com/iotaledger/twin-auditable-item-graph/commit/8fe6cdd0d56496402b766c151f002f475ddb8c0e))
+* update dependencies ([482c97e](https://github.com/iotaledger/twin-auditable-item-graph/commit/482c97e16109e504cb495084ef51e860a7f86669))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/auditable-item-graph-models bumped from 0.0.3-next.14 to 0.0.3-next.15
+
+## [0.0.3-next.14](https://github.com/iotaledger/twin-auditable-item-graph/compare/auditable-item-graph-service-v0.0.3-next.13...auditable-item-graph-service-v0.0.3-next.14) (2026-05-18)
+
+
+### Features
+
+* add versions ([#60](https://github.com/iotaledger/twin-auditable-item-graph/issues/60)) ([5c36f94](https://github.com/iotaledger/twin-auditable-item-graph/commit/5c36f94b1155c01dddbc8d62f3f65d599916c521))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/auditable-item-graph-models bumped from 0.0.3-next.13 to 0.0.3-next.14
+
 ## [0.0.3-next.13](https://github.com/iotaledger/twin-auditable-item-graph/compare/auditable-item-graph-service-v0.0.3-next.12...auditable-item-graph-service-v0.0.3-next.13) (2026-05-12)
 
 

package/docs/open-api/spec.json

@@ -867,6 +867,282 @@
 				}
 			}
 		},
+		"/auditable-item-graph/{id}/versions/{versionId}": {
+			"get": {
+				"operationId": "auditableItemGraphVersionGet",
+				"summary": "Get a graph vertex at a specific version",
+				"tags": [
+					"Auditable Item Graph"
+				],
+				"parameters": [
+					{
+						"name": "id",
+						"description": "The id of the vertex.",
+						"in": "path",
+						"required": true,
+						"schema": {
+							"type": "string"
+						},
+						"style": "simple",
+						"example": "aig:1234567890"
+					},
+					{
+						"name": "versionId",
+						"description": "The id of the version (changeset id) to get.",
+						"in": "path",
+						"required": true,
+						"schema": {
+							"type": "string"
+						},
+						"style": "simple",
+						"example": "changeset:1234567890"
+					},
+					{
+						"name": "accept",
+						"in": "header",
+						"required": true,
+						"schema": {
+							"type": "string"
+						},
+						"style": "simple",
+						"example": "application/json"
+					}
+				],
+				"security": [
+					{
+						"jwtBearerAuthScheme": []
+					}
+				],
+				"responses": {
+					"200": {
+						"description": "Response to getting an auditable item graph vertex at a specific version.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "https://schema.twindev.org/aig/AuditableItemGraphVertex"
+								},
+								"examples": {
+									"auditableItemGraphVersionGetResponseExample": {
+										"value": {
+											"@context": [
+												"https://schema.twindev.org/aig/",
+												"https://schema.twindev.org/common/",
+												"https://schema.org"
+											],
+											"type": "AuditableItemGraphVertex",
+											"id": "aig:1234567890",
+											"dateCreated": "2024-08-22T11:55:16.271Z",
+											"version": 1
+										}
+									}
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "The server cannot process the request, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "GeneralError",
+											"message": "errorMessage",
+											"properties": {
+												"foo": "bar"
+											}
+										}
+									}
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "You are not authorized to use the API or no credentials were supplied, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "UnauthorizedError",
+											"message": "errorMessage"
+										}
+									}
+								}
+							}
+						}
+					},
+					"500": {
+						"description": "The server has encountered a situation it does not know how to handle, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "InternalServerError",
+											"message": "errorMessage"
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/auditable-item-graph/{id}/versions": {
+			"get": {
+				"operationId": "auditableItemGraphVersionList",
+				"summary": "Get all versions of a graph vertex",
+				"tags": [
+					"Auditable Item Graph"
+				],
+				"parameters": [
+					{
+						"name": "id",
+						"description": "The id of the vertex.",
+						"in": "path",
+						"required": true,
+						"schema": {
+							"type": "string"
+						},
+						"style": "simple",
+						"example": "aig:1234567890"
+					},
+					{
+						"name": "after",
+						"description": "Only return versions created after this ISO 8601 timestamp (exclusive).",
+						"in": "query",
+						"required": false,
+						"schema": {
+							"type": "string"
+						}
+					},
+					{
+						"name": "before",
+						"description": "Only return versions created before this ISO 8601 timestamp (exclusive).",
+						"in": "query",
+						"required": false,
+						"schema": {
+							"type": "string"
+						}
+					},
+					{
+						"name": "accept",
+						"in": "header",
+						"required": true,
+						"schema": {
+							"type": "string"
+						},
+						"style": "simple",
+						"example": "application/json"
+					}
+				],
+				"security": [
+					{
+						"jwtBearerAuthScheme": []
+					}
+				],
+				"responses": {
+					"200": {
+						"description": "Response to getting all versions of an auditable item graph vertex.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "https://schema.twindev.org/aig/AuditableItemGraphVertexVersionList"
+								},
+								"examples": {
+									"auditableItemGraphVersionListResponseExample": {
+										"value": {
+											"@context": [
+												"https://schema.org",
+												"https://schema.twindev.org/aig/",
+												"https://schema.twindev.org/common/"
+											],
+											"type": [
+												"ItemList",
+												"AuditableItemGraphVertexVersionList"
+											],
+											"itemListElement": [
+												0,
+												1,
+												2
+											]
+										}
+									}
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "The server cannot process the request, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "GeneralError",
+											"message": "errorMessage",
+											"properties": {
+												"foo": "bar"
+											}
+										}
+									}
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "You are not authorized to use the API or no credentials were supplied, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "UnauthorizedError",
+											"message": "errorMessage"
+										}
+									}
+								}
+							}
+						}
+					},
+					"500": {
+						"description": "The server has encountered a situation it does not know how to handle, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "InternalServerError",
+											"message": "errorMessage"
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
 		"/auditable-item-graph/{id}/changesets/{changesetId}": {
 			"get": {
 				"operationId": "auditableItemGraphChangesetGet",
@@ -1458,6 +1734,10 @@
 					"verified": {
 						"type": "boolean",
 						"description": "Is the vertex verified, will only be populated when verification is requested."
+					},
+					"version": {
+						"type": "number",
+						"description": "The version of the vertex, populated only when getting a specific version.\nMaps to https://schema.org/version."
 					}
 				},
 				"required": [
@@ -1532,6 +1812,10 @@
 					"verified": {
 						"type": "boolean",
 						"description": "Is the vertex verified, will only be populated when verification is requested."
+					},
+					"version": {
+						"type": "number",
+						"description": "The version of the vertex, populated only when getting a specific version.\nMaps to https://schema.org/version."
 					}
 				},
 				"required": [

package/docs/reference/classes/AuditableItemGraphChangeset.md

@@ -59,3 +59,11 @@ The patches in the changeset.
 > `optional` **proofId?**: `string`
 
 The immutable proof id which contains the signature for this changeset.
+
+***
+
+### version? {#version}
+
+> `optional` **version?**: `number`
+
+The version number of the vertex after this changeset was applied.

package/docs/reference/classes/AuditableItemGraphService.md

@@ -70,6 +70,22 @@ The class name of the component.
 
 ***
 
+### start() {#start}
+
+> **start**(): `Promise`\<`void`\>
+
+Register all AIG metrics with the telemetry component.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.start`
+
+***
+
 ### create() {#create}
 
 > **create**(`vertex`): `Promise`\<`string`\>
@@ -260,6 +276,88 @@ NotFoundError if the vertex is not found.
 
 ***
 
+### getVersion() {#getversion}
+
+> **getVersion**(`id`, `versionId`): `Promise`\<`IAuditableItemGraphVertex`\>
+
+Get a graph vertex at a specific version.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the vertex.
+
+##### versionId
+
+`string`
+
+The id of the version (changeset id) to retrieve.
+
+#### Returns
+
+`Promise`\<`IAuditableItemGraphVertex`\>
+
+The vertex reconstructed at that version.
+
+#### Throws
+
+NotFoundError if the vertex or version is not found.
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.getVersion`
+
+***
+
+### getVersions() {#getversions}
+
+> **getVersions**(`id`, `options?`): `Promise`\<`IAuditableItemGraphVertexVersionList`\>
+
+Get all versions of a graph vertex.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the vertex.
+
+##### options?
+
+Additional options for the operation.
+
+###### after?
+
+`string`
+
+Only return versions created after this ISO 8601 timestamp (exclusive).
+
+###### before?
+
+`string`
+
+Only return versions created before this ISO 8601 timestamp (exclusive).
+
+#### Returns
+
+`Promise`\<`IAuditableItemGraphVertexVersionList`\>
+
+The list of vertex versions.
+
+#### Throws
+
+NotFoundError if the vertex is not found.
+
+#### Implementation of
+
+`IAuditableItemGraphComponent.getVersions`
+
+***
+
 ### removeVerifiable() {#removeverifiable}
 
 > **removeVerifiable**(`id`): `Promise`\<`void`\>

package/docs/reference/classes/AuditableItemGraphVertex.md

@@ -91,3 +91,11 @@ The resources attached to the vertex.
 > `optional` **edges?**: [`AuditableItemGraphEdge`](AuditableItemGraphEdge.md)[]
 
 Edges connected to the vertex.
+
+***
+
+### version? {#version}
+
+> `optional` **version?**: `number`
+
+The current version of the vertex, incremented on each changeset.

package/docs/reference/functions/auditableItemGraphVersionGet.md

@@ -0,0 +1,31 @@
+# Function: auditableItemGraphVersionGet()
+
+> **auditableItemGraphVersionGet**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`IAuditableItemGraphVersionGetResponse`\>
+
+Get the graph vertex at a specific version.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`IAuditableItemGraphVersionGetRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`IAuditableItemGraphVersionGetResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/auditableItemGraphVersionList.md

@@ -0,0 +1,31 @@
+# Function: auditableItemGraphVersionList()
+
+> **auditableItemGraphVersionList**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`IAuditableItemGraphVersionListResponse`\>
+
+Get all versions of a graph vertex.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`IAuditableItemGraphVersionListRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`IAuditableItemGraphVersionListResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/index.md

@@ -29,4 +29,6 @@
 - [auditableItemGraphChangesetGet](functions/auditableItemGraphChangesetGet.md)
 - [auditableItemGraphUpdate](functions/auditableItemGraphUpdate.md)
 - [auditableItemGraphList](functions/auditableItemGraphList.md)
+- [auditableItemGraphVersionGet](functions/auditableItemGraphVersionGet.md)
+- [auditableItemGraphVersionList](functions/auditableItemGraphVersionList.md)
 - [initSchema](functions/initSchema.md)

package/docs/reference/interfaces/IAuditableItemGraphServiceConstructorOptions.md

@@ -54,6 +54,14 @@ The event bus component type, defaults to no event bus.
 
 ***
 
+### telemetryComponentType? {#telemetrycomponenttype}
+
+> `optional` **telemetryComponentType?**: `string`
+
+The component type for the optional telemetry component used for event metrics, defaults to no telemetry.
+
+***
+
 ### config? {#config}
 
 > `optional` **config?**: [`IAuditableItemGraphServiceConfig`](IAuditableItemGraphServiceConfig.md)

package/locales/en.json

@@ -4,6 +4,9 @@
 			"namespaceMismatch": "The namespace in the urn \"{id}\" does not match the namespace of the Auditable Item Graph service \"{namespace}\"",
 			"createFailed": "Creating the Auditable Item Graph vertex failed",
 			"getFailed": "Getting the Auditable Item Graph vertex failed",
+			"getVersionFailed": "Getting the Auditable Item Graph vertex version failed",
+			"getVersionsFailed": "Getting the Auditable Item Graph vertex versions failed",
+			"versionNotFound": "The version with the Id \"{notFoundId}\" was not found",
 			"updatingFailed": "Updating the Auditable Item Graph vertex failed",
 			"queryingFailed": "Querying the Auditable Item Graph failed",
 			"removeVerifiableFailed": "Removing the verifiable data the Auditable Item Graph vertex failed",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/auditable-item-graph-service",
-	"version": "0.0.3-next.13",
+	"version": "0.0.3-next.15",
 	"description": "Implements graph lifecycle operations and audited change tracking with API route definitions.",
 	"repository": {
 		"type": "git",
@@ -15,7 +15,7 @@
 	},
 	"dependencies": {
 		"@twin.org/api-models": "next",
-		"@twin.org/auditable-item-graph-models": "0.0.3-next.13",
+		"@twin.org/auditable-item-graph-models": "0.0.3-next.15",
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/crypto": "next",
@@ -27,6 +27,7 @@
 		"@twin.org/nameof": "next",
 		"@twin.org/standards-schema-org": "next",
 		"@twin.org/standards-w3c-did": "next",
+		"@twin.org/telemetry-models": "next",
 		"@twin.org/verifiable-storage-models": "next",
 		"@twin.org/web": "next"
 	},