@twin.org/document-management-service 0.0.3-next.11 → 0.0.3-next.13

package/docs/examples.md

@@ -1 +1,121 @@
-# @twin.org/document-management-service - Examples
+# Document Management Service Examples
+
+Use these snippets to wire the service into existing components and handle a full document lifecycle from creation through querying.
+
+## DocumentManagementService
+
+```typescript
+import { ComponentFactory, Converter } from '@twin.org/core';
+import { DocumentManagementService } from '@twin.org/document-management-service';
+import { UneceDocumentCodeList } from '@twin.org/standards-unece';
+
+// Register concrete components before constructing the service.
+ComponentFactory.register('auditable-item-graph', () => auditableItemGraphComponent);
+ComponentFactory.register('blob-storage', () => blobStorageComponent);
+ComponentFactory.register('attestation', () => attestationComponent);
+ComponentFactory.register('data-processing', () => dataProcessingComponent);
+
+const service = new DocumentManagementService();
+const newBlob = Converter.utf8ToBytes('Initial customs document payload');
+```
+
+```typescript
+const className = service.className();
+console.log(className); // DocumentManagementService
+```
+
+```typescript
+const vertexId = await service.create(
+  'CUS-2026-0100',
+  'customs',
+  UneceDocumentCodeList.CustomsDeclaration,
+  newBlob,
+  {
+    '@context': 'https://schema.org',
+    '@type': 'DigitalDocument',
+    name: 'customs-2026-0100.xml'
+  },
+  [
+    {
+      targetId: 'aig:shipment-123',
+      addAlias: true,
+      aliasAnnotationObject: {
+        '@context': 'https://schema.org',
+        '@type': 'Thing',
+        name: 'Shipment reference'
+      }
+    }
+  ],
+  {
+    createAttestation: true,
+    addAlias: true,
+    aliasAnnotationObject: {
+      '@context': 'https://schema.org',
+      '@type': 'Thing',
+      name: 'Primary document alias'
+    }
+  }
+);
+
+console.log(vertexId); // aig:document-vertex-2
+```
+
+```typescript
+await service.update(
+  'aig:document-vertex-2',
+  Converter.utf8ToBytes('Customs document payload revision 1'),
+  {
+    '@context': 'https://schema.org',
+    '@type': 'CreativeWork',
+    name: 'customs-2026-0100-rev1.xml'
+  },
+  [
+    {
+      targetId: 'aig:shipment-123',
+      addAlias: true,
+      aliasAnnotationObject: {
+        '@context': 'https://schema.org',
+        '@type': 'Thing',
+        name: 'Updated shipment alias'
+      }
+    }
+  ]
+);
+```
+
+```typescript
+const latestDocuments = await service.get(
+  'aig:document-vertex-2',
+  {
+    includeBlobStorageMetadata: true,
+    includeAttestation: true,
+    includeRemoved: false
+  },
+  '0',
+  2
+);
+
+console.log(latestDocuments.entries.itemListElement.length); // 2
+console.log(latestDocuments.cursor); // 2
+```
+
+```typescript
+const revision = await service.getRevision('aig:document-vertex-2', 1, {
+  includeBlobStorageData: true,
+  includeAttestation: true
+});
+
+console.log(revision.documentRevision); // 1
+console.log(revision.documentCode); // Cusdec
+```
+
+```typescript
+await service.removeRevision('aig:document-vertex-2', 1);
+```
+
+```typescript
+const queryResult = await service.query('CUS-2026-0100', '0', 10);
+
+console.log(queryResult.entries.vertices.length); // 1
+console.log(queryResult.cursor); // undefined
+```

package/docs/open-api/spec.json

@@ -1013,32 +1013,29 @@
 	"components": {
 		"schemas": {
 			"Document": {
+				"description": "Interface describing a document.",
 				"type": "object",
 				"properties": {
 					"@context": {
 						"type": "array",
-						"minItems": 3,
-						"description": "JSON-LD Context.",
 						"prefixItems": [
 							{
-								"type": "string",
 								"const": "https://schema.org"
 							},
 							{
-								"type": "string",
 								"const": "https://schema.twindev.org/documents/"
 							},
 							{
-								"type": "string",
 								"const": "https://schema.twindev.org/common/"
 							}
 						],
 						"items": {
 							"$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
-						}
+						},
+						"minItems": 3,
+						"description": "JSON-LD Context."
 					},
 					"type": {
-						"type": "string",
 						"const": "Document",
 						"description": "JSON-LD Type."
 					},
@@ -1048,62 +1045,62 @@
 					},
 					"documentId": {
 						"type": "string",
-						"description": "The id of the document. json-ld type:schema:identifier"
+						"description": "The id of the document."
 					},
 					"documentIdFormat": {
 						"type": "string",
-						"description": "The format of the document id. json-ld type:schema:Text"
+						"description": "The format of the document id."
 					},
 					"documentCode": {
 						"$ref": "https://schema.twindev.org/unece/UneceDocumentCodeList"
 					},
 					"documentRevision": {
 						"type": "number",
-						"description": "The revision of the document as a 0 based index. json-ld type:schema:Integer"
+						"description": "The revision of the document as a 0 based index."
 					},
 					"annotationObject": {
 						"$ref": "https://schema.twindev.org/json-ld/JsonLdNodeObject"
 					},
 					"blobStorageId": {
 						"type": "string",
-						"description": "The blob storage id for the document. json-ld type:schema:identifier"
+						"description": "The blob storage id for the document."
 					},
 					"integrity": {
 						"type": "string",
-						"description": "The integrity of the blob data. json-ld namespace:twin-common"
+						"description": "The integrity of the blob data."
 					},
 					"blobStorageEntry": {
 						"$ref": "https://schema.twindev.org/blob-storage/BlobStorageEntry"
 					},
 					"extractedData": {
-						"description": "The data extracted from the document using data extraction services. json-ld type:json"
+						"description": "The data extracted from the document using data extraction services."
 					},
 					"attestationId": {
 						"type": "string",
-						"description": "The attestation for the document if one was created. json-ld type:schema:identifier"
+						"description": "The attestation for the document if one was created."
 					},
 					"attestationInformation": {
 						"$ref": "https://schema.twindev.org/attestation/AttestationInformation"
 					},
 					"dateCreated": {
 						"type": "string",
-						"description": "The date/time of when the document was created. json-ld namespace:schema"
+						"description": "The date/time of when the document was created."
 					},
 					"dateModified": {
 						"type": "string",
-						"description": "The date/time of when the document was modified. json-ld namespace:schema"
+						"description": "The date/time of when the document was modified."
 					},
 					"dateDeleted": {
 						"type": "string",
-						"description": "The date/time of when the document was deleted, as we never actually remove items. json-ld namespace:schema"
+						"description": "The date/time of when the document was deleted, as we never actually remove items."
 					},
 					"organizationIdentity": {
 						"type": "string",
-						"description": "The organization which added the document to the graph. json-ld namespace:twin-common"
+						"description": "The organization which added the document to the graph."
 					},
 					"userIdentity": {
 						"type": "string",
-						"description": "The user who added the document to the graph. json-ld namespace:twin-common"
+						"description": "The user who added the document to the graph."
 					}
 				},
 				"required": [
@@ -1116,36 +1113,32 @@
 					"blobStorageId",
 					"integrity",
 					"dateCreated"
-				],
-				"description": "Interface describing a document."
+				]
 			},
 			"DocumentList": {
+				"description": "Interface describing a list of document entries.",
 				"type": "object",
 				"properties": {
 					"@context": {
 						"type": "array",
-						"minItems": 3,
-						"description": "JSON-LD Context.",
 						"prefixItems": [
 							{
-								"type": "string",
 								"const": "https://schema.org"
 							},
 							{
-								"type": "string",
 								"const": "https://schema.twindev.org/documents/"
 							},
 							{
-								"type": "string",
 								"const": "https://schema.twindev.org/common/"
 							}
 						],
 						"items": {
 							"$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
-						}
+						},
+						"minItems": 3,
+						"description": "JSON-LD Context."
 					},
 					"type": {
-						"type": "string",
 						"const": "ItemList",
 						"description": "JSON-LD Type."
 					},
@@ -1154,22 +1147,21 @@
 						"items": {
 							"$ref": "#/components/schemas/Document"
 						},
-						"description": "The list of documents. json-ld namespace:schema"
+						"description": "The list of documents."
 					},
 					"edges": {
 						"type": "array",
 						"items": {
 							"type": "string"
 						},
-						"description": "The ids of the other vertices which are connected to the document. json-ld container:set"
+						"description": "The ids of the other vertices which are connected to the document."
 					}
 				},
 				"required": [
 					"@context",
 					"type",
 					"itemListElement"
-				],
-				"description": "Interface describing a list of document entries."
+				]
 			},
 			"DocumentManagementCreateRequest": {
 				"type": "object",
@@ -1209,8 +1201,7 @@
 							},
 							"required": [
 								"targetId"
-							],
-							"additionalProperties": false
+							]
 						},
 						"description": "The auditable item graph vertices to connect the document to."
 					},
@@ -1228,6 +1219,7 @@
 				},
 				"required": [
 					"documentId",
+					"documentIdFormat",
 					"documentCode",
 					"blob"
 				],
@@ -1260,8 +1252,7 @@
 							},
 							"required": [
 								"targetId"
-							],
-							"additionalProperties": false
+							]
 						},
 						"description": "The auditable item graph vertices to connect the document to."
 					}
@@ -1269,6 +1260,7 @@
 				"description": "The body parameters."
 			},
 			"Error": {
+				"description": "Model to describe serialized error.",
 				"type": "object",
 				"properties": {
 					"name": {
@@ -1277,7 +1269,7 @@
 					},
 					"message": {
 						"type": "string",
-						"description": "The message for the error."
+						"description": "The message for the error as an i18n key."
 					},
 					"source": {
 						"type": "string",
@@ -1299,8 +1291,7 @@
 				"required": [
 					"name",
 					"message"
-				],
-				"description": "Model to describe serialized error."
+				]
 			},
 			"NotFoundResponse": {
 				"type": "object",
@@ -1308,35 +1299,12 @@
 					"notFoundId": {
 						"type": "string",
 						"description": "The id if the item that was not found."
-					},
-					"name": {
-						"type": "string",
-						"description": "The name for the error."
-					},
-					"message": {
-						"type": "string",
-						"description": "The message for the error."
-					},
-					"source": {
-						"type": "string",
-						"description": "The source of the error."
-					},
-					"properties": {
-						"type": "object",
-						"additionalProperties": {},
-						"description": "Any additional information for the error."
-					},
-					"stack": {
-						"type": "string",
-						"description": "The stack trace for the error."
-					},
-					"cause": {
-						"$ref": "#/components/schemas/Error"
 					}
 				},
-				"required": [
-					"message",
-					"name"
+				"allOf": [
+					{
+						"$ref": "#/components/schemas/Error"
+					}
 				],
 				"description": "The body which contains the error."
 			}

package/docs/reference/classes/DocumentManagementService.md

@@ -28,7 +28,7 @@ The options for the service.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -36,7 +36,7 @@ Runtime name for the class.
 
 ## Methods
 
-### className()
+### className() {#classname}
 
 > **className**(): `string`
 
@@ -54,7 +54,7 @@ The class name of the component.
 
 ***
 
-### create()
+### create() {#create}
 
 > **create**(`documentId`, `documentIdFormat`, `documentCode`, `blob`, `annotationObject?`, `auditableItemGraphEdges?`, `options?`): `Promise`\<`string`\>
 
@@ -72,9 +72,9 @@ The document id to create.
 
 ##### documentIdFormat
 
-The format of the document identifier.
+`string` \| `undefined`
 
-`string` | `undefined`
+The format of the document identifier.
 
 ##### documentCode
 
@@ -134,7 +134,7 @@ The auditable item graph vertex created for the document including its revision.
 
 ***
 
-### update()
+### update() {#update}
 
 > **update**(`auditableItemGraphDocumentId`, `blob?`, `annotationObject?`, `auditableItemGraphEdges?`): `Promise`\<`void`\>
 
@@ -180,7 +180,7 @@ Nothing.
 
 ***
 
-### get()
+### get() {#get}
 
 > **get**(`auditableItemGraphDocumentId`, `options?`, `cursor?`, `limit?`): `Promise`\<\{ `entries`: `IDocumentList`; `cursor?`: `string`; \}\>
 
@@ -258,7 +258,7 @@ The documents and revisions if requested, ordered by revision descending, cursor
 
 ***
 
-### getRevision()
+### getRevision() {#getrevision}
 
 > **getRevision**(`auditableItemGraphDocumentId`, `revision`, `options?`): `Promise`\<`IDocument`\>
 
@@ -324,7 +324,7 @@ The documents and revisions if requested, ordered by revision descending, cursor
 
 ***
 
-### removeRevision()
+### removeRevision() {#removerevision}
 
 > **removeRevision**(`auditableItemGraphDocumentId`, `revision`): `Promise`\<`void`\>
 
@@ -357,7 +357,7 @@ Nothing.
 
 ***
 
-### query()
+### query() {#query}
 
 > **query**(`documentId`, `cursor?`, `limit?`): `Promise`\<\{ `entries`: `IAuditableItemGraphVertexList`; `cursor?`: `string`; \}\>
 

package/docs/reference/interfaces/IDocumentManagementServiceConstructorOptions.md

@@ -4,9 +4,9 @@ Options for the document management Service constructor.
 
 ## Properties
 
-### auditableItemGraphComponentType?
+### auditableItemGraphComponentType? {#auditableitemgraphcomponenttype}
 
-> `optional` **auditableItemGraphComponentType**: `string`
+> `optional` **auditableItemGraphComponentType?**: `string`
 
 The type of the auditable item graph component.
 
@@ -18,9 +18,9 @@ auditable-item-graph
 
 ***
 
-### blobStorageComponentType?
+### blobStorageComponentType? {#blobstoragecomponenttype}
 
-> `optional` **blobStorageComponentType**: `string`
+> `optional` **blobStorageComponentType?**: `string`
 
 The type of the blob storage component.
 
@@ -32,9 +32,9 @@ blob-storage
 
 ***
 
-### attestationComponentType?
+### attestationComponentType? {#attestationcomponenttype}
 
-> `optional` **attestationComponentType**: `string`
+> `optional` **attestationComponentType?**: `string`
 
 The type of the attestation component.
 
@@ -46,9 +46,9 @@ attestation
 
 ***
 
-### dataProcessingComponentType?
+### dataProcessingComponentType? {#dataprocessingcomponenttype}
 
-> `optional` **dataProcessingComponentType**: `string`
+> `optional` **dataProcessingComponentType?**: `string`
 
 The type of the data processing component.
 
@@ -60,8 +60,8 @@ data-processing
 
 ***
 
-### config?
+### config? {#config}
 
-> `optional` **config**: [`IDocumentManagementServiceConfig`](IDocumentManagementServiceConfig.md)
+> `optional` **config?**: [`IDocumentManagementServiceConfig`](IDocumentManagementServiceConfig.md)
 
 The configuration for the service.

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "@twin.org/document-management-service",
-	"version": "0.0.3-next.11",
-	"description": "Document management contract implementation and REST endpoint definitions",
+	"version": "0.0.3-next.13",
+	"description": "Service-side document lifecycle operations and REST route generation for server integrations.",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/twinfoundation/document-management.git",
+		"url": "git+https://github.com/iotaledger/document-management.git",
 		"directory": "packages/document-management-service"
 	},
 	"author": "martyn.janes@iota.org",
@@ -23,7 +23,7 @@
 		"@twin.org/crypto": "next",
 		"@twin.org/data-json-ld": "next",
 		"@twin.org/data-processing-models": "next",
-		"@twin.org/document-management-models": "0.0.3-next.11",
+		"@twin.org/document-management-models": "0.0.3-next.13",
 		"@twin.org/entity": "next",
 		"@twin.org/entity-storage-models": "next",
 		"@twin.org/nameof": "next",
@@ -63,7 +63,7 @@
 		"business-logic"
 	],
 	"bugs": {
-		"url": "git+https://github.com/twinfoundation/document-management/issues"
+		"url": "git+https://github.com/iotaledger/document-management/issues"
 	},
 	"homepage": "https://twindev.org"
 }