@twin.org/document-management-rest-client 0.0.3-next.9 → 0.9.0

package/docs/examples.md

@@ -1 +1,118 @@
-# @twin.org/document-management-rest-client - Examples
+# Document Management REST Client Examples
+
+These examples walk through common client calls for creating, updating, reading, and finding documents from a remote service.
+
+## DocumentManagementRestClient
+
+```typescript
+import { DocumentManagementRestClient } from '@twin.org/document-management-rest-client';
+import { Converter } from '@twin.org/core';
+import { UneceDocumentCodeList } from '@twin.org/standards-unece';
+
+const client = new DocumentManagementRestClient({
+  endpoint: 'http://localhost:3000'
+});
+
+const blobBytes = Converter.utf8ToBytes('Updated bill of lading payload');
+const edgeTargetId = 'aig:shipment-vertex';
+```
+
+```typescript
+const componentName = client.className();
+console.log(componentName); // DocumentManagementRestClient
+```
+
+```typescript
+const createdVertexId = await client.create(
+  'BOL-2026-0001',
+  'bol',
+  UneceDocumentCodeList.BillOfLading,
+  blobBytes,
+  {
+    '@context': 'https://schema.org',
+    '@type': 'DigitalDocument',
+    name: 'bol-2026-0001.pdf'
+  },
+  [
+    {
+      targetId: edgeTargetId,
+      addAlias: true,
+      aliasAnnotationObject: {
+        '@context': 'https://schema.org',
+        '@type': 'Thing',
+        name: 'Shipment link'
+      }
+    }
+  ],
+  {
+    createAttestation: true,
+    addAlias: true,
+    aliasAnnotationObject: {
+      '@context': 'https://schema.org',
+      '@type': 'Thing',
+      name: 'Primary alias'
+    }
+  }
+);
+
+console.log(createdVertexId); // aig:document-vertex-1
+```
+
+```typescript
+await client.update(
+  'aig:document-vertex-1',
+  Converter.utf8ToBytes('Second revision payload'),
+  {
+    '@context': 'https://schema.org',
+    '@type': 'CreativeWork',
+    name: 'bol-2026-0001-rev1.pdf'
+  },
+  [
+    {
+      targetId: edgeTargetId,
+      addAlias: true,
+      aliasAnnotationObject: {
+        '@context': 'https://schema.org',
+        '@type': 'Thing',
+        name: 'Shipment alias'
+      }
+    }
+  ]
+);
+```
+
+```typescript
+const latest = await client.get(
+  'aig:document-vertex-1',
+  {
+    includeBlobStorageMetadata: true,
+    includeAttestation: true
+  },
+  '0',
+  2
+);
+
+console.log(latest.entries.itemListElement.length); // 2
+console.log(latest.cursor); // 2
+```
+
+```typescript
+const revisionOne = await client.getRevision('aig:document-vertex-1', 1, {
+  includeBlobStorageData: true,
+  includeAttestation: true
+});
+
+console.log(revisionOne.documentRevision); // 1
+console.log(revisionOne.documentId); // BOL-2026-0001
+```
+
+```typescript
+await client.removeRevision('aig:document-vertex-1', 1);
+```
+
+```typescript
+const matches = await client.query('BOL-2026-0001', '0', 10);
+
+console.log(matches.entries.vertices.length); // 1
+console.log(matches.cursor); // undefined
+```

package/docs/reference/classes/DocumentManagementRestClient.md

@@ -36,7 +36,7 @@ The configuration for the client.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -44,7 +44,7 @@ Runtime name for the class.
 
 ## Methods
 
-### className()
+### className() {#classname}
 
 > **className**(): `string`
 
@@ -62,9 +62,9 @@ The class name of the component.
 
 ***
 
-### create()
+### create() {#create}
 
-> **create**(`documentId`, `documentIdFormat`, `documentCode`, `blob`, `annotationObject?`, `auditableItemGraphEdges?`, `options?`): `Promise`\<`string`\>
+> **create**(`document`, `blob`, `auditableItemGraphEdges?`, `options?`): `Promise`\<`string`\>
 
 Store 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.
@@ -72,39 +72,21 @@ For any other changes the current revision will be updated.
 
 #### Parameters
 
-##### documentId
-
-`string`
-
-The document id to create.
-
-##### documentIdFormat
-
-The format of the document identifier.
+##### document
 
-`string` | `undefined`
+`IDocumentBase`
 
-##### documentCode
-
-`UneceDocumentCodeList`
-
-The code for the document type.
+The document base properties.
 
 ##### blob
 
-`Uint8Array`
-
-The data to create the document with.
-
-##### annotationObject?
-
-`IJsonLdNodeObject`
+`string` \| `Uint8Array`\<`ArrayBufferLike`\>
 
-Additional information to associate with the document.
+The data to create the document with as bytes, or an existing blob storage entry id.
 
 ##### auditableItemGraphEdges?
 
-`object`[]
+`IDocumentManagementEdgeEntry`[]
 
 The auditable item graph vertices to connect the document to.
 
@@ -112,13 +94,13 @@ The auditable item graph vertices to connect the document to.
 
 Additional options for the set operation.
 
-###### createAttestation?
+###### includeAttestation?
 
 `boolean`
 
 Flag to create an attestation for the document, defaults to false.
 
-###### addAlias?
+###### includeAlias?
 
 `boolean`
 
@@ -142,9 +124,9 @@ The auditable item graph vertex created for the document including its revision.
 
 ***
 
-### update()
+### updatePartial() {#updatepartial}
 
-> **update**(`auditableItemGraphDocumentId`, `blob?`, `annotationObject?`, `auditableItemGraphEdges?`): `Promise`\<`void`\>
+> **updatePartial**(`auditableItemGraphDocumentId`, `document?`, `blob?`, `auditableItemGraphEdges?`, `options?`): `Promise`\<`void`\>
 
 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.
@@ -158,37 +140,73 @@ For any other changes the current revision will be updated.
 
 The auditable item graph vertex id which contains the document.
 
-##### blob?
+##### document?
 
-`Uint8Array`\<`ArrayBufferLike`\>
+`Partial`\<`Pick`\<`IDocumentBase`, `"annotationObject"` \| `"documentIdFormat"` \| `"documentCode"`\>\>
 
-The data to update the document with.
+The document base properties to update. annotationObject, documentIdFormat and documentCode are applied in-place to the current revision.
 
-##### annotationObject?
+##### blob?
 
-`IJsonLdNodeObject`
+`string` \| `Uint8Array`\<`ArrayBufferLike`\>
 
-Additional information to associate with the document.
+The data to update the document with as bytes, or an existing blob storage entry id.
 
 ##### auditableItemGraphEdges?
 
-`object`[]
+Explicit edge delta to apply. If undefined, existing connections
+are retained unchanged. Use `add` to create new connections and `remove` to disconnect existing
+ones by their target vertex id. To update alias metadata on an already-connected vertex, include
+it in `add` with the updated `aliasAnnotationObject` — AIG's alias patch is an upsert, so the
+alias is updated in place without creating a duplicate back-edge.
+
+###### add?
 
-The auditable item graph vertices to connect the document to, if undefined retains current connections.
+`IDocumentManagementEdgeEntry`[]
+
+Connections to add; each creates a back-edge on the connected vertex.
+
+###### remove?
+
+`string`[]
+
+Target vertex IDs to disconnect; their back-edges are removed.
+
+##### options?
+
+Additional options for the update operation.
+
+###### includeAttestation?
+
+`boolean`
+
+Set to true to start attesting the document, or false to remove the existing attestation. Omit to leave unchanged.
+
+###### includeAlias?
+
+`boolean`
+
+Set to true to add the document id as an alias on the aig vertex, or false to remove it. Omit to leave unchanged.
+
+###### aliasAnnotationObject?
+
+`IJsonLdNodeObject`
+
+Annotation object for the alias when adding.
 
 #### Returns
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the document has been updated.
 
 #### Implementation of
 
-`IDocumentManagementComponent.update`
+`IDocumentManagementComponent.updatePartial`
 
 ***
 
-### get()
+### get() {#get}
 
 > **get**(`auditableItemGraphDocumentId`, `options?`, `cursor?`, `limit?`): `Promise`\<\{ `entries`: `IDocumentList`; `cursor?`: `string`; \}\>
 
@@ -230,6 +248,12 @@ Flag to include the attestation information for the document, defaults to false.
 
 Flag to include deleted documents, defaults to false.
 
+###### includeDeletedEdges?
+
+`boolean`
+
+Flag to include soft-deleted edges in the response, defaults to false.
+
 ###### extractRuleGroupId?
 
 `string`
@@ -266,9 +290,9 @@ The documents and revisions if requested, ordered by revision descending, cursor
 
 ***
 
-### getRevision()
+### getRevision() {#getrevision}
 
-> **getRevision**(`auditableItemGraphDocumentId`, `revision`, `options?`): `Promise`\<`IDocument`\>
+> **getRevision**(`auditableItemGraphDocumentId`, `revision`, `options?`): `Promise`\<`IDocumentHydrated`\>
 
 Get a document revision using it's auditable item graph vertex id.
 
@@ -322,9 +346,9 @@ By default extraction will auto detect the mime type of the document, this can b
 
 #### Returns
 
-`Promise`\<`IDocument`\>
+`Promise`\<`IDocumentHydrated`\>
 
-The documents and revisions if requested, ordered by revision descending, cursor is set if there are more document revisions.
+The document for the specified revision.
 
 #### Implementation of
 
@@ -332,7 +356,7 @@ The documents and revisions if requested, ordered by revision descending, cursor
 
 ***
 
-### removeRevision()
+### removeRevision() {#removerevision}
 
 > **removeRevision**(`auditableItemGraphDocumentId`, `revision`): `Promise`\<`void`\>
 
@@ -357,7 +381,7 @@ The revision of the document to remove.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the revision has been removed.
 
 #### Implementation of
 
@@ -365,7 +389,7 @@ Nothing.
 
 ***
 
-### query()
+### query() {#query}
 
 > **query**(`documentId`, `cursor?`, `limit?`): `Promise`\<\{ `entries`: `IAuditableItemGraphVertexList`; `cursor?`: `string`; \}\>
 

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "@twin.org/document-management-rest-client",
-	"version": "0.0.3-next.9",
-	"description": "Document management contract implementation which can connect to REST endpoints",
+	"version": "0.9.0",
+	"description": "REST client operations for creating, updating, retrieving, and querying managed documents.",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/twinfoundation/document-management.git",
+		"url": "git+https://github.com/iotaledger/twin-document-management.git",
 		"directory": "packages/document-management-rest-client"
 	},
 	"author": "martyn.janes@iota.org",
@@ -14,16 +14,16 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@twin.org/api-core": "next",
-		"@twin.org/api-models": "next",
-		"@twin.org/auditable-item-graph-models": "next",
-		"@twin.org/core": "next",
-		"@twin.org/data-json-ld": "next",
-		"@twin.org/document-management-models": "0.0.3-next.9",
-		"@twin.org/entity": "next",
-		"@twin.org/nameof": "next",
-		"@twin.org/standards-unece": "next",
-		"@twin.org/web": "next"
+		"@twin.org/api-core": "^0.9.0",
+		"@twin.org/api-models": "^0.9.0",
+		"@twin.org/auditable-item-graph-models": "^0.9.0",
+		"@twin.org/core": "^0.9.0",
+		"@twin.org/data-json-ld": "^0.9.0",
+		"@twin.org/document-management-models": "^0.9.0",
+		"@twin.org/entity": "^0.9.0",
+		"@twin.org/nameof": "^0.9.0",
+		"@twin.org/standards-unece": "^0.9.0",
+		"@twin.org/web": "^0.9.0"
 	},
 	"main": "./dist/es/index.js",
 	"types": "./dist/types/index.d.ts",
@@ -54,7 +54,7 @@
 		"rest-api"
 	],
 	"bugs": {
-		"url": "git+https://github.com/twinfoundation/document-management/issues"
+		"url": "git+https://github.com/iotaledger/twin-document-management/issues"
 	},
 	"homepage": "https://twindev.org"
 }