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

package/docs/examples.md

@@ -1 +1,183 @@
-# @twin.org/auditable-item-stream-rest-client - Examples
+# Auditable Item Stream REST Client Examples
+
+These snippets show practical client-side workflows for creating streams, managing entries, and paging through results.
+
+## AuditableItemStreamRestClient
+
+```typescript
+import { AuditableItemStreamRestClient } from '@twin.org/auditable-item-stream-rest-client';
+import type { IBaseRestClientConfig } from '@twin.org/api-models';
+
+const config: IBaseRestClientConfig = {
+  endpoint: 'http://localhost:3000'
+};
+
+const client = new AuditableItemStreamRestClient(config);
+console.log(client.className()); // AuditableItemStreamRestClient
+```
+
+```typescript
+import { AuditableItemStreamRestClient } from '@twin.org/auditable-item-stream-rest-client';
+import type { IBaseRestClientConfig } from '@twin.org/api-models';
+
+const config: IBaseRestClientConfig = {
+  endpoint: 'http://localhost:3000'
+};
+
+const client = new AuditableItemStreamRestClient(config);
+
+const streamId = await client.create(
+  {
+    annotationObject: {
+      '@context': 'https://schema.org',
+      '@type': 'CreativeWork',
+      name: 'Monthly Compliance Report'
+    },
+    entries: [
+      {
+        entryObject: {
+          '@context': 'https://schema.org',
+          '@type': 'Event',
+          name: 'Report created'
+        }
+      }
+    ]
+  },
+  {
+    immutableInterval: 5
+  }
+);
+
+const stream = await client.get(streamId, {
+  includeEntries: true,
+  verifyStream: true,
+  verifyEntries: true
+});
+
+await client.update({
+  id: streamId,
+  annotationObject: {
+    '@context': 'https://schema.org',
+    '@type': 'CreativeWork',
+    name: 'Monthly Compliance Report v2'
+  }
+});
+
+console.log(stream.id); // ais:...
+console.log(stream.numberOfItems); // 1
+```
+
+```typescript
+import { AuditableItemStreamRestClient } from '@twin.org/auditable-item-stream-rest-client';
+import type { IBaseRestClientConfig } from '@twin.org/api-models';
+import { ComparisonOperator, SortDirection } from '@twin.org/entity';
+
+const config: IBaseRestClientConfig = {
+  endpoint: 'http://localhost:3000'
+};
+
+const client = new AuditableItemStreamRestClient(config);
+
+const firstPage = await client.query(
+  [
+    {
+      property: 'organizationIdentity',
+      comparison: ComparisonOperator.Equals,
+      value: 'did:iota:org:123'
+    }
+  ],
+  'dateCreated',
+  SortDirection.Descending,
+  ['id', 'dateCreated', 'dateModified', 'numberOfItems'],
+  'cursor:page-1',
+  10
+);
+
+console.log(firstPage.entries.itemListElement.length); // 10
+console.log(firstPage.cursor); // eyJjdXJzb3IiOiIuLi4ifQ==
+```
+
+```typescript
+import { AuditableItemStreamRestClient } from '@twin.org/auditable-item-stream-rest-client';
+import type { IBaseRestClientConfig } from '@twin.org/api-models';
+
+const config: IBaseRestClientConfig = {
+  endpoint: 'http://localhost:3000'
+};
+
+const client = new AuditableItemStreamRestClient(config);
+const streamId = 'ais:0f4f9de65dc44f31b4a474a0cc93ce69';
+
+const entryId = await client.createEntry(streamId, {
+  '@context': 'https://schema.org',
+  '@type': 'Message',
+  text: 'Status changed to approved'
+});
+
+const entry = await client.getEntry(streamId, entryId, {
+  verifyEntry: true
+});
+
+await client.updateEntry(streamId, entryId, {
+  '@context': 'https://schema.org',
+  '@type': 'Message',
+  text: 'Status changed to approved by reviewer'
+});
+
+const entryObject = await client.getEntryObject(streamId, entryId);
+console.log(entry.id); // ais:0f4f9de65dc44f31b4a474a0cc93ce69:...
+console.log(entryObject['@type']); // Message
+
+await client.removeEntry(streamId, entryId);
+```
+
+```typescript
+import { AuditableItemStreamRestClient } from '@twin.org/auditable-item-stream-rest-client';
+import type { IBaseRestClientConfig } from '@twin.org/api-models';
+import { SortDirection } from '@twin.org/entity';
+
+const config: IBaseRestClientConfig = {
+  endpoint: 'http://localhost:3000'
+};
+
+const client = new AuditableItemStreamRestClient(config);
+const streamId = 'ais:0f4f9de65dc44f31b4a474a0cc93ce69';
+
+const entryList = await client.getEntries(streamId, {
+  includeDeleted: false,
+  verifyEntries: false,
+  limit: 20,
+  order: SortDirection.Ascending
+});
+
+const entryObjectList = await client.getEntryObjects(streamId, {
+  includeDeleted: true,
+  limit: 20,
+  order: SortDirection.Descending
+});
+
+console.log(entryList.entries.itemListElement.length); // 20
+console.log(entryObjectList.entries.itemListElement.length); // 20
+```
+
+```typescript
+import { AuditableItemStreamRestClient } from '@twin.org/auditable-item-stream-rest-client';
+import type { IBaseRestClientConfig } from '@twin.org/api-models';
+
+const config: IBaseRestClientConfig = {
+  endpoint: 'http://localhost:3000'
+};
+
+const client = new AuditableItemStreamRestClient(config);
+const streamId = 'ais:0f4f9de65dc44f31b4a474a0cc93ce69';
+
+try {
+  await client.removeVerifiable(streamId);
+} catch (error) {
+  if (error instanceof Error) {
+    console.log(error.name); // NotSupportedError
+  }
+}
+
+await client.remove(streamId);
+```

package/docs/reference/classes/AuditableItemStreamRestClient.md

@@ -8,7 +8,7 @@ Client for performing auditable item stream through to REST endpoints.
 
 ## Implements
 
-- `IAuditableItemStreamComponent`
+- `Omit`\<`IAuditableItemStreamComponent`, `"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,13 +58,13 @@ The class name of the component.
 
 #### Implementation of
 
-`IAuditableItemStreamComponent.className`
+`Omit.className`
 
 ***
 
-### create()
+### create() {#create}
 
-> **create**(`stream`, `options?`): `Promise`\<`string`\>
+> **create**(`stream`): `Promise`\<`string`\>
 
 Create a new stream.
 
@@ -72,30 +72,9 @@ Create a new stream.
 
 ##### stream
 
-The stream to create.
-
-###### annotationObject?
-
-`IJsonLdNodeObject`
-
-The object for the stream as JSON-LD.
-
-###### entries?
-
-`object`[]
+`IAuditableItemStreamBase`
 
-Entries to store in the stream.
-
-##### options?
-
-Options for creating the stream.
-
-###### immutableInterval?
-
-`number`
-
-After how many entries do we add immutable checks, defaults to service configured value.
-A value of 0 will disable integrity checks, 1 will be every item, or any other integer for an interval.
+The stream to create.
 
 #### Returns
 
@@ -105,13 +84,13 @@ The id of the new stream item.
 
 #### Implementation of
 
-`IAuditableItemStreamComponent.create`
+`Omit.create`
 
 ***
 
-### get()
+### get() {#get}
 
-> **get**(`id`, `options?`): `Promise`\<`IAuditableItemStream`\>
+> **get**(`id`, `cursor?`, `limit?`, `options?`): `Promise`\<\{ `stream`: `IAuditableItemStream`; `cursor?`: `string`; \}\>
 
 Get a stream header without the entries.
 
@@ -123,6 +102,18 @@ Get a stream header without the entries.
 
 The id of the stream to get.
 
+##### cursor?
+
+`string`
+
+Cursor to use for next chunk of entries.
+
+##### limit?
+
+`number`
+
+Limit the number of entries to return, only applicable if includeEntries is true.
+
 ##### options?
 
 Additional options for the get operation.
@@ -153,7 +144,7 @@ Should the entries be verified, defaults to false.
 
 #### Returns
 
-`Promise`\<`IAuditableItemStream`\>
+`Promise`\<\{ `stream`: `IAuditableItemStream`; `cursor?`: `string`; \}\>
 
 The stream and entries if found.
 
@@ -163,11 +154,11 @@ NotFoundError if the stream is not found
 
 #### Implementation of
 
-`IAuditableItemStreamComponent.get`
+`Omit.get`
 
 ***
 
-### update()
+### update() {#update}
 
 > **update**(`stream`): `Promise`\<`void`\>
 
@@ -177,19 +168,35 @@ Update a stream.
 
 ##### stream
 
-The stream to update.
+`Pick`\<`IAuditableItemStream`, `"@context"` \| `"type"` \| `"id"` \| `"annotationObject"`\>
 
-###### id
+The stream to update, does not update entries.
 
-`string`
+#### Returns
 
-The id of the stream to update.
+`Promise`\<`void`\>
 
-###### annotationObject?
+Nothing.
 
-`IJsonLdNodeObject`
+#### Implementation of
 
-The object for the stream as JSON-LD.
+`Omit.update`
+
+***
+
+### close() {#close}
+
+> **close**(`id`): `Promise`\<`void`\>
+
+Close the stream.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the stream to close.
 
 #### Returns
 
@@ -199,11 +206,11 @@ Nothing.
 
 #### Implementation of
 
-`IAuditableItemStreamComponent.update`
+`Omit.close`
 
 ***
 
-### remove()
+### remove() {#remove}
 
 > **remove**(`id`): `Promise`\<`void`\>
 
@@ -225,13 +232,13 @@ Nothing.
 
 #### Implementation of
 
-`IAuditableItemStreamComponent.remove`
+`Omit.remove`
 
 ***
 
-### query()
+### query() {#query}
 
-> **query**(`conditions?`, `orderBy?`, `orderByDirection?`, `properties?`, `cursor?`, `limit?`): `Promise`\<`IAuditableItemStreamList`\>
+> **query**(`conditions?`, `orderBy?`, `orderByDirection?`, `properties?`, `cursor?`, `limit?`): `Promise`\<\{ `entries`: `IAuditableItemStreamList`; `cursor?`: `string`; \}\>
 
 Query all the streams, will not return entries.
 
@@ -245,9 +252,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?
 
@@ -275,17 +282,17 @@ Limit the number of entities to return.
 
 #### Returns
 
-`Promise`\<`IAuditableItemStreamList`\>
+`Promise`\<\{ `entries`: `IAuditableItemStreamList`; `cursor?`: `string`; \}\>
 
 The entities, which can be partial if a limited keys list was provided.
 
 #### Implementation of
 
-`IAuditableItemStreamComponent.query`
+`Omit.query`
 
 ***
 
-### createEntry()
+### createEntry() {#createentry}
 
 > **createEntry**(`id`, `entryObject`): `Promise`\<`string`\>
 
@@ -313,11 +320,11 @@ The id of the created entry, if not provided.
 
 #### Implementation of
 
-`IAuditableItemStreamComponent.createEntry`
+`Omit.createEntry`
 
 ***
 
-### getEntry()
+### getEntry() {#getentry}
 
 > **getEntry**(`id`, `entryId`, `options?`): `Promise`\<`IAuditableItemStreamEntry`\>
 
@@ -359,11 +366,11 @@ NotFoundError if the stream is not found.
 
 #### Implementation of
 
-`IAuditableItemStreamComponent.getEntry`
+`Omit.getEntry`
 
 ***
 
-### getEntryObject()
+### getEntryObject() {#getentryobject}
 
 > **getEntryObject**(`id`, `entryId`): `Promise`\<`IJsonLdNodeObject`\>
 
@@ -395,11 +402,11 @@ NotFoundError if the stream is not found.
 
 #### Implementation of
 
-`IAuditableItemStreamComponent.getEntryObject`
+`Omit.getEntryObject`
 
 ***
 
-### updateEntry()
+### updateEntry() {#updateentry}
 
 > **updateEntry**(`id`, `entryId`, `entryObject`): `Promise`\<`void`\>
 
@@ -433,11 +440,11 @@ Nothing.
 
 #### Implementation of
 
-`IAuditableItemStreamComponent.updateEntry`
+`Omit.updateEntry`
 
 ***
 
-### removeEntry()
+### removeEntry() {#removeentry}
 
 > **removeEntry**(`id`, `entryId`): `Promise`\<`void`\>
 
@@ -465,23 +472,23 @@ Nothing.
 
 #### Implementation of
 
-`IAuditableItemStreamComponent.removeEntry`
+`Omit.removeEntry`
 
 ***
 
-### getEntries()
+### getEntries() {#getentries}
 
-> **getEntries**(`id`, `options?`): `Promise`\<`IAuditableItemStreamEntryList`\>
+> **getEntries**(`id?`, `options?`): `Promise`\<\{ `entries`: `IAuditableItemStreamEntryList`; `cursor?`: `string`; \}\>
 
 Get the entries for the stream.
 
 #### Parameters
 
-##### id
+##### id?
 
 `string`
 
-The id of the stream to get.
+The id of the stream to get, if undefined returns all matching entries.
 
 ##### options?
 
@@ -525,7 +532,7 @@ Retrieve the entries in ascending/descending time order, defaults to Ascending.
 
 #### Returns
 
-`Promise`\<`IAuditableItemStreamEntryList`\>
+`Promise`\<\{ `entries`: `IAuditableItemStreamEntryList`; `cursor?`: `string`; \}\>
 
 The stream and entries if found.
 
@@ -535,23 +542,23 @@ NotFoundError if the stream is not found.
 
 #### Implementation of
 
-`IAuditableItemStreamComponent.getEntries`
+`Omit.getEntries`
 
 ***
 
-### getEntryObjects()
+### getEntryObjects() {#getentryobjects}
 
-> **getEntryObjects**(`id`, `options?`): `Promise`\<`IAuditableItemStreamEntryObjectList`\>
+> **getEntryObjects**(`id?`, `options?`): `Promise`\<\{ `entries`: `IAuditableItemStreamEntryObjectList`; `cursor?`: `string`; \}\>
 
 Get the entry objects for the stream.
 
 #### Parameters
 
-##### id
+##### id?
 
 `string`
 
-The id of the stream to get.
+The id of the stream to get, if undefined returns all matching entries.
 
 ##### options?
 
@@ -589,7 +596,7 @@ Retrieve the entries in ascending/descending time order, defaults to Ascending.
 
 #### Returns
 
-`Promise`\<`IAuditableItemStreamEntryObjectList`\>
+`Promise`\<\{ `entries`: `IAuditableItemStreamEntryObjectList`; `cursor?`: `string`; \}\>
 
 The stream and entries if found.
 
@@ -599,34 +606,4 @@ NotFoundError if the stream is not found.
 
 #### Implementation of
 
-`IAuditableItemStreamComponent.getEntryObjects`
-
-***
-
-### removeVerifiable()
-
-> **removeVerifiable**(`id`): `Promise`\<`void`\>
-
-Remove the verifiable storage for the stream and entries, not supported on client.
-
-#### Parameters
-
-##### id
-
-`string`
-
-The id of the stream to remove the storage from.
-
-#### Returns
-
-`Promise`\<`void`\>
-
-Nothing.
-
-#### Throws
-
-NotFoundError if the vertex is not found.
-
-#### Implementation of
-
-`IAuditableItemStreamComponent.removeVerifiable`
+`Omit.getEntryObjects`

package/locales/en.json

@@ -1,7 +1 @@
-{
-	"error": {
-		"auditableItemStreamRestClient": {
-			"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-stream-rest-client",
-	"version": "0.0.3-next.2",
-	"description": "Auditable Item Stream contract implementation which can connect to REST endpoints",
+	"version": "0.0.3-next.20",
+	"description": "HTTP client for interacting with auditable stream service endpoints.",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/twinfoundation/auditable-item-stream.git",
+		"url": "git+https://github.com/iotaledger/twin-auditable-item-stream.git",
 		"directory": "packages/auditable-item-stream-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-stream-models": "0.0.3-next.2",
+		"@twin.org/auditable-item-stream-models": "0.0.3-next.20",
 		"@twin.org/core": "next",
 		"@twin.org/data-json-ld": "next",
 		"@twin.org/entity": "next",
@@ -48,7 +48,7 @@
 		"auditable-item-stream"
 	],
 	"bugs": {
-		"url": "git+https://github.com/twinfoundation/auditable-item-stream/issues"
+		"url": "git+https://github.com/iotaledger/twin-auditable-item-stream/issues"
 	},
 	"homepage": "https://twindev.org"
 }