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

package/docs/examples.md

@@ -1 +1,119 @@
-# @twin.org/auditable-item-graph-rest-client - Examples
+# Auditable Item Graph REST Client Examples
+
+These snippets show practical request flows for creating, reading, updating, and querying graph items through HTTP endpoints.
+
+## AuditableItemGraphRestClient
+
+```typescript
+import { AuditableItemGraphRestClient } from '@twin.org/auditable-item-graph-rest-client';
+
+const client = new AuditableItemGraphRestClient({ endpoint: 'http://localhost:8080' });
+
+console.log(client.className()); // AuditableItemGraphRestClient
+```
+
+```typescript
+import { VerifyDepth } from '@twin.org/auditable-item-graph-models';
+import { AuditableItemGraphRestClient } from '@twin.org/auditable-item-graph-rest-client';
+
+const client = new AuditableItemGraphRestClient({ endpoint: 'http://localhost:8080' });
+
+const id = await client.create({
+  annotationObject: {
+    '@context': 'https://www.w3.org/ns/activitystreams',
+    type: 'Create',
+    actor: {
+      type: 'Person',
+      id: 'acct:alex@example.org',
+      name: 'Alex'
+    },
+    object: {
+      type: 'Note',
+      content: 'Created through the REST client'
+    }
+  },
+  aliases: [{ id: 'ticket-2026-0007', aliasFormat: 'externalRef', unique: true }],
+  resources: [
+    { resourceObject: { '@context': 'https://schema.org', type: 'Thing', name: 'Asset A' } }
+  ]
+});
+
+const vertex = await client.get(id, {
+  includeDeleted: false,
+  verifySignatureDepth: VerifyDepth.Current
+});
+
+console.log(id); // aig:018f5a6cfd9444d58c7c2d4df1fd0a23
+console.log(vertex.id); // aig:018f5a6cfd9444d58c7c2d4df1fd0a23
+```
+
+```typescript
+import { VerifyDepth } from '@twin.org/auditable-item-graph-models';
+import { AuditableItemGraphRestClient } from '@twin.org/auditable-item-graph-rest-client';
+
+const client = new AuditableItemGraphRestClient({ endpoint: 'http://localhost:8080' });
+
+const id = 'aig:018f5a6cfd9444d58c7c2d4df1fd0a23';
+
+await client.update({
+  id,
+  aliases: [{ id: 'ticket-2026-0007', aliasFormat: 'externalRef' }],
+  resources: [
+    {
+      id: 'resource-1',
+      resourceObject: { '@context': 'https://schema.org', type: 'Thing', name: 'Asset A v2' }
+    }
+  ],
+  edges: [{ targetId: 'aig:018f5a6cfd9444d58c7c2d4df1fd0999', edgeRelationships: ['dependsOn'] }]
+});
+
+const changesetChunk = await client.getChangesets(id, undefined, 20, {
+  verifySignatureDepth: VerifyDepth.Current
+});
+
+const firstChangeset = changesetChunk.changesets.itemListElement?.[0];
+
+if (firstChangeset?.id) {
+  const changeset = await client.getChangeset(firstChangeset.id, {
+    verifySignatureDepth: VerifyDepth.Current
+  });
+
+  console.log(changeset.id); // aig:018f5a6cfd9444d58c7c2d4df1fd0a23:changeset:018f5a6cfd9444d58c7c2d4df1fd0b10
+}
+```
+
+```typescript
+import { AuditableItemGraphRestClient } from '@twin.org/auditable-item-graph-rest-client';
+import { ComparisonOperator, SortDirection } from '@twin.org/entity';
+
+const client = new AuditableItemGraphRestClient({ endpoint: 'http://localhost:8080' });
+
+const result = await client.query(
+  {
+    id: 'ticket-2026',
+    idMode: 'alias',
+    idExact: false,
+    resourceTypes: ['Thing']
+  },
+  [
+    {
+      field: 'dateCreated',
+      comparison: ComparisonOperator.GreaterThan,
+      value: '2026-01-01T00:00:00.000Z'
+    }
+  ],
+  'dateCreated',
+  SortDirection.Descending,
+  ['id', 'dateCreated', 'aliases'],
+  undefined,
+  10
+);
+
+console.log(result.entries.itemListElement?.length ?? 0); // 2
+
+try {
+  await client.removeVerifiable('aig:018f5a6cfd9444d58c7c2d4df1fd0a23');
+} catch (error) {
+  console.log(error instanceof Error ? error.message : 'Unknown error'); // Not supported on client
+}
+```

package/docs/reference/classes/AuditableItemGraphRestClient.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,7 +62,7 @@ The class name of the component.
 
 ***
 
-### create()
+### create() {#create}
 
 > **create**(`vertex`): `Promise`\<`string`\>
 
@@ -72,31 +72,9 @@ Create a new graph vertex.
 
 ##### vertex
 
-The vertex to create.
-
-###### annotationObject?
-
-`IJsonLdNodeObject`
-
-The annotation object for the vertex as JSON-LD.
-
-###### aliases?
-
-`object`[]
-
-Alternative aliases that can be used to identify the vertex.
-
-###### resources?
-
-`object`[]
-
-The resources attached to the vertex.
-
-###### edges?
-
-`object`[]
+`Omit`\<`IAuditableItemGraphVertex`, `"id"`\>
 
-The edges connected to the vertex.
+The vertex to create.
 
 #### Returns
 
@@ -110,7 +88,7 @@ The id of the new graph item.
 
 ***
 
-### get()
+### get() {#get}
 
 > **get**(`id`, `options?`): `Promise`\<`IAuditableItemGraphVertex`\>
 
@@ -156,7 +134,7 @@ NotFoundError if the vertex is not found.
 
 ***
 
-### getChangesets()
+### getChangesets() {#getchangesets}
 
 > **getChangesets**(`id`, `cursor?`, `limit?`, `options?`): `Promise`\<\{ `changesets`: `IAuditableItemGraphChangesetList`; `cursor?`: `string`; \}\>
 
@@ -204,7 +182,7 @@ The changesets if found.
 
 ***
 
-### getChangeset()
+### getChangeset() {#getchangeset}
 
 > **getChangeset**(`id`, `options?`): `Promise`\<`IAuditableItemGraphChangeset`\>
 
@@ -244,53 +222,109 @@ NotFoundError if the vertex or changeset is not found.
 
 ***
 
-### update()
+### getVersion() {#getversion}
 
-> **update**(`vertex`): `Promise`\<`void`\>
+> **getVersion**(`id`, `version`): `Promise`\<`IAuditableItemGraphVertex`\>
 
-Update a graph vertex.
+Get a graph vertex at a specific version.
 
 #### Parameters
 
-##### vertex
+##### id
 
-The vertex to update.
+`string`
+
+The id of the vertex.
+
+##### version
+
+`number`
+
+The version number 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`
 
-###### id
+The id of the vertex.
+
+##### options?
+
+Additional options for the operation.
+
+###### after?
 
 `string`
 
-The id of the vertex to update.
+Only return versions created after this ISO 8601 timestamp (exclusive).
+
+###### before?
 
-###### annotationObject?
+`string`
 
-`IJsonLdNodeObject`
+Only return versions created before this ISO 8601 timestamp (exclusive).
 
-The annotation object for the vertex as JSON-LD.
+#### Returns
 
-###### aliases?
+`Promise`\<`IAuditableItemGraphVertexVersionList`\>
 
-`object`[]
+The list of vertex versions.
 
-Alternative aliases that can be used to identify the vertex.
+#### Throws
 
-###### resources?
+NotFoundError if the vertex is not found.
 
-`object`[]
+#### Implementation of
 
-The resources attached to the vertex.
+`IAuditableItemGraphComponent.getVersions`
 
-###### edges?
+***
 
-`object`[]
+### update() {#update}
 
-The edges connected to the vertex.
+> **update**(`vertex`): `Promise`\<`void`\>
+
+Update a graph vertex (PUT — full replacement of vertex state).
+The server serializes concurrent updates for the same vertex via `Mutex` on the vertex id;
+requests load-balanced across replicas can still race.
+
+#### Parameters
+
+##### vertex
+
+`IAuditableItemGraphVertex`
+
+The vertex to update.
 
 #### Returns
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the vertex has been updated.
 
 #### Implementation of
 
@@ -298,37 +332,59 @@ Nothing.
 
 ***
 
-### removeVerifiable()
+### updatePartial() {#updatepartial}
 
-> **removeVerifiable**(`id`): `Promise`\<`void`\>
+> **updatePartial**(`partial`): `Promise`\<`void`\>
 
-Remove the verifiable storage for an item, not supported on client.
+Partially update a graph vertex (PATCH — optional scalars; list fields use `{ add, remove }`).
 
 #### Parameters
 
-##### id
+##### partial
 
-`string`
+`IAuditableItemGraphPartialVertex`
 
-The id of the vertex to get.
+The partial vertex update (must include `id`).
 
 #### Returns
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the partial update has been applied.
 
-#### Throws
+#### Implementation of
 
-NotFoundError if the vertex is not found.
+`IAuditableItemGraphComponent.updatePartial`
+
+***
+
+### removeProof() {#removeproof}
+
+> **removeProof**(`id`): `Promise`\<`void`\>
+
+Remove the notarization proof from all changesets of a graph vertex.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the vertex.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the proof has been removed.
 
 #### Implementation of
 
-`IAuditableItemGraphComponent.removeVerifiable`
+`IAuditableItemGraphComponent.removeProof`
 
 ***
 
-### query()
+### query() {#query}
 
 > **query**(`options?`, `conditions?`, `orderBy?`, `orderByDirection?`, `properties?`, `cursor?`, `limit?`): `Promise`\<\{ `entries`: `IAuditableItemGraphVertexList`; `cursor?`: `string`; \}\>
 
@@ -366,15 +422,15 @@ Include vertices with specific resource types.
 
 ##### conditions?
 
-`IComparator`[]
+`EntityCondition`\<`IAuditableItemGraphVertex`\>
 
 Conditions to use in the query.
 
 ##### orderBy?
 
-The order for the results, defaults to created.
+`"dateCreated"` \| `"dateModified"`
 
-`"dateCreated"` | `"dateModified"`
+The order for the results, defaults to created.
 
 ##### orderByDirection?
 

package/locales/en.json

@@ -1,7 +1 @@
-{
-	"error": {
-		"auditableItemGraphRestClient": {
-			"notSupportedOnClient": "The method \"{methodName}\" is not supported on the REST client, it can only be used on a server side component"
-		}
-	}
-}
+{}

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "@twin.org/auditable-item-graph-rest-client",
-	"version": "0.0.3-next.8",
-	"description": "Auditable Item Graph contract implementation which can connect to REST endpoints",
+	"version": "0.9.0-next.2",
+	"description": "Provides a client for interacting with auditable graph endpoints over HTTP.",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/twinfoundation/auditable-item-graph.git",
+		"url": "git+https://github.com/iotaledger/twin-auditable-item-graph.git",
 		"directory": "packages/auditable-item-graph-rest-client"
 	},
 	"author": "martyn.janes@iota.org",
@@ -16,7 +16,7 @@
 	"dependencies": {
 		"@twin.org/api-core": "next",
 		"@twin.org/api-models": "next",
-		"@twin.org/auditable-item-graph-models": "0.0.3-next.8",
+		"@twin.org/auditable-item-graph-models": "0.9.0-next.2",
 		"@twin.org/core": "next",
 		"@twin.org/data-json-ld": "next",
 		"@twin.org/entity": "next",
@@ -49,7 +49,7 @@
 		"auditable-item-graph"
 	],
 	"bugs": {
-		"url": "git+https://github.com/twinfoundation/auditable-item-graph/issues"
+		"url": "git+https://github.com/iotaledger/twin-auditable-item-graph/issues"
 	},
 	"homepage": "https://twindev.org"
 }