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

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

@@ -8,7 +8,7 @@ Client for performing auditable item graph through to REST endpoints.
 
 ## Implements
 
-- `IAuditableItemGraphComponent`
+- `Omit`\<`IAuditableItemGraphComponent`, `"removeProof"`\>
 
 ## Constructors
 
@@ -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`
 
@@ -58,11 +58,11 @@ The class name of the component.
 
 #### Implementation of
 
-`IAuditableItemGraphComponent.className`
+`Omit.className`
 
 ***
 
-### create()
+### create() {#create}
 
 > **create**(`vertex`): `Promise`\<`string`\>
 
@@ -72,49 +72,73 @@ Create a new graph vertex.
 
 ##### vertex
 
+`Omit`\<`IAuditableItemGraphVertex`, `"id"`\>
+
 The vertex to create.
 
-###### annotationObject?
+#### Returns
 
-`IJsonLdNodeObject`
+`Promise`\<`string`\>
+
+The id of the new graph item.
 
-The annotation object for the vertex as JSON-LD.
+#### Implementation of
+
+`Omit.create`
+
+***
 
-###### aliases?
+### get() {#get}
 
-`object`[]
+> **get**(`id`, `options?`): `Promise`\<`IAuditableItemGraphVertex`\>
 
-Alternative aliases that can be used to identify the vertex.
+Get a graph vertex.
 
-###### resources?
+#### Parameters
 
-`object`[]
+##### id
 
-The resources attached to the vertex.
+`string`
 
-###### edges?
+The id of the vertex to get.
 
-`object`[]
+##### options?
 
-The edges connected to the vertex.
+Additional options for the get operation.
+
+###### includeDeleted?
+
+`boolean`
+
+Whether to include deleted/updated aliases, resource, edges, defaults to false.
+
+###### verifySignatureDepth?
+
+`VerifyDepth`
+
+How many signatures to verify, defaults to "none".
 
 #### Returns
 
-`Promise`\<`string`\>
+`Promise`\<`IAuditableItemGraphVertex`\>
 
-The id of the new graph item.
+The vertex if found.
+
+#### Throws
+
+NotFoundError if the vertex is not found.
 
 #### Implementation of
 
-`IAuditableItemGraphComponent.create`
+`Omit.get`
 
 ***
 
-### get()
+### getChangesets() {#getchangesets}
 
-> **get**(`id`, `options?`): `Promise`\<`IAuditableItemGraphVertex`\>
+> **getChangesets**(`id`, `cursor?`, `limit?`, `options?`): `Promise`\<\{ `changesets`: `IAuditableItemGraphChangesetList`; `cursor?`: `string`; \}\>
 
-Get a graph vertex.
+Get a graph vertex changeset list.
 
 #### Parameters
 
@@ -124,21 +148,57 @@ Get a graph vertex.
 
 The id of the vertex to get.
 
+##### cursor?
+
+`string`
+
+The optional cursor to get next chunk.
+
+##### limit?
+
+`number`
+
+Limit the number of entities to return.
+
 ##### options?
 
 Additional options for the get operation.
 
-###### includeDeleted?
+###### verifySignatureDepth?
 
-`boolean`
+`VerifyDepth`
 
-Whether to include deleted/updated aliases, resource, edges, defaults to false.
+How many signatures to verify, defaults to "none".
 
-###### includeChangesets?
+#### Returns
 
-`boolean`
+`Promise`\<\{ `changesets`: `IAuditableItemGraphChangesetList`; `cursor?`: `string`; \}\>
+
+The changesets if found.
+
+#### Implementation of
+
+`Omit.getChangesets`
+
+***
+
+### getChangeset() {#getchangeset}
+
+> **getChangeset**(`id`, `options?`): `Promise`\<`IAuditableItemGraphChangeset`\>
+
+Get a graph vertex changeset.
+
+#### Parameters
+
+##### id
 
-Whether to include the changesets of the vertex, defaults to false.
+`string`
+
+The id of the vertex to get.
+
+##### options?
+
+Additional options for the get operation.
 
 ###### verifySignatureDepth?
 
@@ -148,61 +208,117 @@ How many signatures to verify, defaults to "none".
 
 #### Returns
 
+`Promise`\<`IAuditableItemGraphChangeset`\>
+
+The changeset if found.
+
+#### Throws
+
+NotFoundError if the vertex or changeset is not found.
+
+#### Implementation of
+
+`Omit.getChangeset`
+
+***
+
+### getVersion() {#getversion}
+
+> **getVersion**(`id`, `version`): `Promise`\<`IAuditableItemGraphVertex`\>
+
+Get a graph vertex at a specific version.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the vertex.
+
+##### version
+
+`number`
+
+The version number to retrieve.
+
+#### Returns
+
 `Promise`\<`IAuditableItemGraphVertex`\>
 
-The vertex if found.
+The vertex reconstructed at that version.
 
 #### Throws
 
-NotFoundError if the vertex is not found.
+NotFoundError if the vertex or version is not found.
 
 #### Implementation of
 
-`IAuditableItemGraphComponent.get`
+`Omit.getVersion`
 
 ***
 
-### update()
+### getVersions() {#getversions}
 
-> **update**(`vertex`): `Promise`\<`void`\>
+> **getVersions**(`id`, `options?`): `Promise`\<`IAuditableItemGraphVertexVersionList`\>
 
-Update a graph vertex.
+Get all versions of a graph vertex.
 
 #### Parameters
 
-##### vertex
+##### id
 
-The vertex to update.
+`string`
+
+The id of the vertex.
+
+##### options?
 
-###### id
+Additional options for the operation.
+
+###### after?
 
 `string`
 
-The id of the vertex to update.
+Only return versions created after this ISO 8601 timestamp (exclusive).
 
-###### annotationObject?
+###### before?
 
-`IJsonLdNodeObject`
+`string`
 
-The annotation object for the vertex as JSON-LD.
+Only return versions created before this ISO 8601 timestamp (exclusive).
 
-###### aliases?
+#### Returns
 
-`object`[]
+`Promise`\<`IAuditableItemGraphVertexVersionList`\>
 
-Alternative aliases that can be used to identify the vertex.
+The list of vertex versions.
 
-###### resources?
+#### Throws
 
-`object`[]
+NotFoundError if the vertex is not found.
 
-The resources attached to the vertex.
+#### Implementation of
+
+`Omit.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
 
@@ -212,23 +328,23 @@ Nothing.
 
 #### Implementation of
 
-`IAuditableItemGraphComponent.update`
+`Omit.update`
 
 ***
 
-### 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
 
@@ -236,19 +352,15 @@ The id of the vertex to get.
 
 Nothing.
 
-#### Throws
-
-NotFoundError if the vertex is not found.
-
 #### Implementation of
 
-`IAuditableItemGraphComponent.removeVerifiable`
+`Omit.updatePartial`
 
 ***
 
-### query()
+### query() {#query}
 
-> **query**(`options?`, `conditions?`, `orderBy?`, `orderByDirection?`, `properties?`, `cursor?`, `limit?`): `Promise`\<`IAuditableItemGraphVertexList`\>
+> **query**(`options?`, `conditions?`, `orderBy?`, `orderByDirection?`, `properties?`, `cursor?`, `limit?`): `Promise`\<\{ `entries`: `IAuditableItemGraphVertexList`; `cursor?`: `string`; \}\>
 
 Query the graph for vertices.
 
@@ -290,9 +402,9 @@ 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?
 
@@ -320,10 +432,10 @@ Limit the number of entities to return.
 
 #### Returns
 
-`Promise`\<`IAuditableItemGraphVertexList`\>
+`Promise`\<\{ `entries`: `IAuditableItemGraphVertexList`; `cursor?`: `string`; \}\>
 
 The entities, which can be partial if a limited keys list was provided.
 
 #### Implementation of
 
-`IAuditableItemGraphComponent.query`
+`Omit.query`

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.2",
-	"description": "Auditable Item Graph contract implementation which can connect to REST endpoints",
+	"version": "0.0.3-next.20",
+	"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.2",
+		"@twin.org/auditable-item-graph-models": "0.0.3-next.20",
 		"@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"
 }