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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/examples.md CHANGED
@@ -1 +1,183 @@
1
- # @twin.org/auditable-item-stream-rest-client - Examples
1
+ # Auditable Item Stream REST Client Examples
2
+
3
+ These snippets show practical client-side workflows for creating streams, managing entries, and paging through results.
4
+
5
+ ## AuditableItemStreamRestClient
6
+
7
+ ```typescript
8
+ import { AuditableItemStreamRestClient } from '@twin.org/auditable-item-stream-rest-client';
9
+ import type { IBaseRestClientConfig } from '@twin.org/api-models';
10
+
11
+ const config: IBaseRestClientConfig = {
12
+ endpoint: 'http://localhost:3000'
13
+ };
14
+
15
+ const client = new AuditableItemStreamRestClient(config);
16
+ console.log(client.className()); // AuditableItemStreamRestClient
17
+ ```
18
+
19
+ ```typescript
20
+ import { AuditableItemStreamRestClient } from '@twin.org/auditable-item-stream-rest-client';
21
+ import type { IBaseRestClientConfig } from '@twin.org/api-models';
22
+
23
+ const config: IBaseRestClientConfig = {
24
+ endpoint: 'http://localhost:3000'
25
+ };
26
+
27
+ const client = new AuditableItemStreamRestClient(config);
28
+
29
+ const streamId = await client.create(
30
+ {
31
+ annotationObject: {
32
+ '@context': 'https://schema.org',
33
+ '@type': 'CreativeWork',
34
+ name: 'Monthly Compliance Report'
35
+ },
36
+ entries: [
37
+ {
38
+ entryObject: {
39
+ '@context': 'https://schema.org',
40
+ '@type': 'Event',
41
+ name: 'Report created'
42
+ }
43
+ }
44
+ ]
45
+ },
46
+ {
47
+ immutableInterval: 5
48
+ }
49
+ );
50
+
51
+ const stream = await client.get(streamId, {
52
+ includeEntries: true,
53
+ verifyStream: true,
54
+ verifyEntries: true
55
+ });
56
+
57
+ await client.update({
58
+ id: streamId,
59
+ annotationObject: {
60
+ '@context': 'https://schema.org',
61
+ '@type': 'CreativeWork',
62
+ name: 'Monthly Compliance Report v2'
63
+ }
64
+ });
65
+
66
+ console.log(stream.id); // ais:...
67
+ console.log(stream.numberOfItems); // 1
68
+ ```
69
+
70
+ ```typescript
71
+ import { AuditableItemStreamRestClient } from '@twin.org/auditable-item-stream-rest-client';
72
+ import type { IBaseRestClientConfig } from '@twin.org/api-models';
73
+ import { ComparisonOperator, SortDirection } from '@twin.org/entity';
74
+
75
+ const config: IBaseRestClientConfig = {
76
+ endpoint: 'http://localhost:3000'
77
+ };
78
+
79
+ const client = new AuditableItemStreamRestClient(config);
80
+
81
+ const firstPage = await client.query(
82
+ [
83
+ {
84
+ property: 'organizationIdentity',
85
+ comparison: ComparisonOperator.Equals,
86
+ value: 'did:iota:org:123'
87
+ }
88
+ ],
89
+ 'dateCreated',
90
+ SortDirection.Descending,
91
+ ['id', 'dateCreated', 'dateModified', 'numberOfItems'],
92
+ 'cursor:page-1',
93
+ 10
94
+ );
95
+
96
+ console.log(firstPage.entries.itemListElement.length); // 10
97
+ console.log(firstPage.cursor); // eyJjdXJzb3IiOiIuLi4ifQ==
98
+ ```
99
+
100
+ ```typescript
101
+ import { AuditableItemStreamRestClient } from '@twin.org/auditable-item-stream-rest-client';
102
+ import type { IBaseRestClientConfig } from '@twin.org/api-models';
103
+
104
+ const config: IBaseRestClientConfig = {
105
+ endpoint: 'http://localhost:3000'
106
+ };
107
+
108
+ const client = new AuditableItemStreamRestClient(config);
109
+ const streamId = 'ais:0f4f9de65dc44f31b4a474a0cc93ce69';
110
+
111
+ const entryId = await client.createEntry(streamId, {
112
+ '@context': 'https://schema.org',
113
+ '@type': 'Message',
114
+ text: 'Status changed to approved'
115
+ });
116
+
117
+ const entry = await client.getEntry(streamId, entryId, {
118
+ verifyEntry: true
119
+ });
120
+
121
+ await client.updateEntry(streamId, entryId, {
122
+ '@context': 'https://schema.org',
123
+ '@type': 'Message',
124
+ text: 'Status changed to approved by reviewer'
125
+ });
126
+
127
+ const entryObject = await client.getEntryObject(streamId, entryId);
128
+ console.log(entry.id); // ais:0f4f9de65dc44f31b4a474a0cc93ce69:...
129
+ console.log(entryObject['@type']); // Message
130
+
131
+ await client.removeEntry(streamId, entryId);
132
+ ```
133
+
134
+ ```typescript
135
+ import { AuditableItemStreamRestClient } from '@twin.org/auditable-item-stream-rest-client';
136
+ import type { IBaseRestClientConfig } from '@twin.org/api-models';
137
+ import { SortDirection } from '@twin.org/entity';
138
+
139
+ const config: IBaseRestClientConfig = {
140
+ endpoint: 'http://localhost:3000'
141
+ };
142
+
143
+ const client = new AuditableItemStreamRestClient(config);
144
+ const streamId = 'ais:0f4f9de65dc44f31b4a474a0cc93ce69';
145
+
146
+ const entryList = await client.getEntries(streamId, {
147
+ includeDeleted: false,
148
+ verifyEntries: false,
149
+ limit: 20,
150
+ order: SortDirection.Ascending
151
+ });
152
+
153
+ const entryObjectList = await client.getEntryObjects(streamId, {
154
+ includeDeleted: true,
155
+ limit: 20,
156
+ order: SortDirection.Descending
157
+ });
158
+
159
+ console.log(entryList.entries.itemListElement.length); // 20
160
+ console.log(entryObjectList.entries.itemListElement.length); // 20
161
+ ```
162
+
163
+ ```typescript
164
+ import { AuditableItemStreamRestClient } from '@twin.org/auditable-item-stream-rest-client';
165
+ import type { IBaseRestClientConfig } from '@twin.org/api-models';
166
+
167
+ const config: IBaseRestClientConfig = {
168
+ endpoint: 'http://localhost:3000'
169
+ };
170
+
171
+ const client = new AuditableItemStreamRestClient(config);
172
+ const streamId = 'ais:0f4f9de65dc44f31b4a474a0cc93ce69';
173
+
174
+ try {
175
+ await client.removeVerifiable(streamId);
176
+ } catch (error) {
177
+ if (error instanceof Error) {
178
+ console.log(error.name); // NotSupportedError
179
+ }
180
+ }
181
+
182
+ await client.remove(streamId);
183
+ ```
@@ -36,7 +36,7 @@ The configuration for the client.
36
36
 
37
37
  ## Properties
38
38
 
39
- ### CLASS\_NAME
39
+ ### CLASS\_NAME {#class_name}
40
40
 
41
41
  > `readonly` `static` **CLASS\_NAME**: `string`
42
42
 
@@ -44,7 +44,7 @@ Runtime name for the class.
44
44
 
45
45
  ## Methods
46
46
 
47
- ### className()
47
+ ### className() {#classname}
48
48
 
49
49
  > **className**(): `string`
50
50
 
@@ -62,9 +62,9 @@ The class name of the component.
62
62
 
63
63
  ***
64
64
 
65
- ### create()
65
+ ### create() {#create}
66
66
 
67
- > **create**(`stream`, `options?`): `Promise`\<`string`\>
67
+ > **create**(`stream`): `Promise`\<`string`\>
68
68
 
69
69
  Create a new stream.
70
70
 
@@ -72,30 +72,9 @@ Create a new stream.
72
72
 
73
73
  ##### stream
74
74
 
75
- The stream to create.
76
-
77
- ###### annotationObject?
78
-
79
- `IJsonLdNodeObject`
80
-
81
- The object for the stream as JSON-LD.
82
-
83
- ###### entries?
84
-
85
- `object`[]
86
-
87
- Entries to store in the stream.
88
-
89
- ##### options?
90
-
91
- Options for creating the stream.
75
+ `IAuditableItemStreamBase`
92
76
 
93
- ###### immutableInterval?
94
-
95
- `number`
96
-
97
- After how many entries do we add immutable checks, defaults to service configured value.
98
- A value of 0 will disable integrity checks, 1 will be every item, or any other integer for an interval.
77
+ The stream to create.
99
78
 
100
79
  #### Returns
101
80
 
@@ -109,9 +88,9 @@ The id of the new stream item.
109
88
 
110
89
  ***
111
90
 
112
- ### get()
91
+ ### get() {#get}
113
92
 
114
- > **get**(`id`, `options?`): `Promise`\<`IAuditableItemStream`\>
93
+ > **get**(`id`, `cursor?`, `limit?`, `options?`): `Promise`\<\{ `stream`: `IAuditableItemStream`; `cursor?`: `string`; \}\>
115
94
 
116
95
  Get a stream header without the entries.
117
96
 
@@ -123,6 +102,18 @@ Get a stream header without the entries.
123
102
 
124
103
  The id of the stream to get.
125
104
 
105
+ ##### cursor?
106
+
107
+ `string`
108
+
109
+ Cursor to use for next chunk of entries.
110
+
111
+ ##### limit?
112
+
113
+ `number`
114
+
115
+ Limit the number of entries to return, only applicable if includeEntries is true.
116
+
126
117
  ##### options?
127
118
 
128
119
  Additional options for the get operation.
@@ -153,7 +144,7 @@ Should the entries be verified, defaults to false.
153
144
 
154
145
  #### Returns
155
146
 
156
- `Promise`\<`IAuditableItemStream`\>
147
+ `Promise`\<\{ `stream`: `IAuditableItemStream`; `cursor?`: `string`; \}\>
157
148
 
158
149
  The stream and entries if found.
159
150
 
@@ -167,7 +158,7 @@ NotFoundError if the stream is not found
167
158
 
168
159
  ***
169
160
 
170
- ### update()
161
+ ### update() {#update}
171
162
 
172
163
  > **update**(`stream`): `Promise`\<`void`\>
173
164
 
@@ -177,19 +168,61 @@ Update a stream.
177
168
 
178
169
  ##### stream
179
170
 
180
- The stream to update.
171
+ `Pick`\<`IAuditableItemStream`, `"@context"` \| `"type"` \| `"id"` \| `"annotationObject"`\>
172
+
173
+ The stream to update, does not update entries.
174
+
175
+ #### Returns
176
+
177
+ `Promise`\<`void`\>
178
+
179
+ Nothing.
180
+
181
+ #### Implementation of
182
+
183
+ `IAuditableItemStreamComponent.update`
184
+
185
+ ***
186
+
187
+ ### close() {#close}
188
+
189
+ > **close**(`id`): `Promise`\<`void`\>
190
+
191
+ Close the stream.
181
192
 
182
- ###### id
193
+ #### Parameters
194
+
195
+ ##### id
183
196
 
184
197
  `string`
185
198
 
186
- The id of the stream to update.
199
+ The id of the stream to close.
187
200
 
188
- ###### annotationObject?
201
+ #### Returns
189
202
 
190
- `IJsonLdNodeObject`
203
+ `Promise`\<`void`\>
191
204
 
192
- The object for the stream as JSON-LD.
205
+ Nothing.
206
+
207
+ #### Implementation of
208
+
209
+ `IAuditableItemStreamComponent.close`
210
+
211
+ ***
212
+
213
+ ### removeProof() {#removeproof}
214
+
215
+ > **removeProof**(`streamId`): `Promise`\<`void`\>
216
+
217
+ Remove the notarization proof from a stream.
218
+
219
+ #### Parameters
220
+
221
+ ##### streamId
222
+
223
+ `string`
224
+
225
+ The id of the stream.
193
226
 
194
227
  #### Returns
195
228
 
@@ -199,11 +232,11 @@ Nothing.
199
232
 
200
233
  #### Implementation of
201
234
 
202
- `IAuditableItemStreamComponent.update`
235
+ `IAuditableItemStreamComponent.removeProof`
203
236
 
204
237
  ***
205
238
 
206
- ### remove()
239
+ ### remove() {#remove}
207
240
 
208
241
  > **remove**(`id`): `Promise`\<`void`\>
209
242
 
@@ -229,9 +262,9 @@ Nothing.
229
262
 
230
263
  ***
231
264
 
232
- ### query()
265
+ ### query() {#query}
233
266
 
234
- > **query**(`conditions?`, `orderBy?`, `orderByDirection?`, `properties?`, `cursor?`, `limit?`): `Promise`\<`IAuditableItemStreamList`\>
267
+ > **query**(`conditions?`, `orderBy?`, `orderByDirection?`, `properties?`, `cursor?`, `limit?`): `Promise`\<\{ `entries`: `IAuditableItemStreamList`; `cursor?`: `string`; \}\>
235
268
 
236
269
  Query all the streams, will not return entries.
237
270
 
@@ -245,9 +278,9 @@ Conditions to use in the query.
245
278
 
246
279
  ##### orderBy?
247
280
 
248
- The order for the results, defaults to created.
281
+ `"dateCreated"` \| `"dateModified"`
249
282
 
250
- `"dateCreated"` | `"dateModified"`
283
+ The order for the results, defaults to created.
251
284
 
252
285
  ##### orderByDirection?
253
286
 
@@ -275,7 +308,7 @@ Limit the number of entities to return.
275
308
 
276
309
  #### Returns
277
310
 
278
- `Promise`\<`IAuditableItemStreamList`\>
311
+ `Promise`\<\{ `entries`: `IAuditableItemStreamList`; `cursor?`: `string`; \}\>
279
312
 
280
313
  The entities, which can be partial if a limited keys list was provided.
281
314
 
@@ -285,7 +318,7 @@ The entities, which can be partial if a limited keys list was provided.
285
318
 
286
319
  ***
287
320
 
288
- ### createEntry()
321
+ ### createEntry() {#createentry}
289
322
 
290
323
  > **createEntry**(`id`, `entryObject`): `Promise`\<`string`\>
291
324
 
@@ -317,7 +350,7 @@ The id of the created entry, if not provided.
317
350
 
318
351
  ***
319
352
 
320
- ### getEntry()
353
+ ### getEntry() {#getentry}
321
354
 
322
355
  > **getEntry**(`id`, `entryId`, `options?`): `Promise`\<`IAuditableItemStreamEntry`\>
323
356
 
@@ -363,7 +396,7 @@ NotFoundError if the stream is not found.
363
396
 
364
397
  ***
365
398
 
366
- ### getEntryObject()
399
+ ### getEntryObject() {#getentryobject}
367
400
 
368
401
  > **getEntryObject**(`id`, `entryId`): `Promise`\<`IJsonLdNodeObject`\>
369
402
 
@@ -399,7 +432,7 @@ NotFoundError if the stream is not found.
399
432
 
400
433
  ***
401
434
 
402
- ### updateEntry()
435
+ ### updateEntry() {#updateentry}
403
436
 
404
437
  > **updateEntry**(`id`, `entryId`, `entryObject`): `Promise`\<`void`\>
405
438
 
@@ -437,7 +470,7 @@ Nothing.
437
470
 
438
471
  ***
439
472
 
440
- ### removeEntry()
473
+ ### removeEntry() {#removeentry}
441
474
 
442
475
  > **removeEntry**(`id`, `entryId`): `Promise`\<`void`\>
443
476
 
@@ -469,19 +502,19 @@ Nothing.
469
502
 
470
503
  ***
471
504
 
472
- ### getEntries()
505
+ ### getEntries() {#getentries}
473
506
 
474
- > **getEntries**(`id`, `options?`): `Promise`\<`IAuditableItemStreamEntryList`\>
507
+ > **getEntries**(`id?`, `options?`): `Promise`\<\{ `entries`: `IAuditableItemStreamEntryList`; `cursor?`: `string`; \}\>
475
508
 
476
509
  Get the entries for the stream.
477
510
 
478
511
  #### Parameters
479
512
 
480
- ##### id
513
+ ##### id?
481
514
 
482
515
  `string`
483
516
 
484
- The id of the stream to get.
517
+ The id of the stream to get, if undefined returns all matching entries.
485
518
 
486
519
  ##### options?
487
520
 
@@ -525,7 +558,7 @@ Retrieve the entries in ascending/descending time order, defaults to Ascending.
525
558
 
526
559
  #### Returns
527
560
 
528
- `Promise`\<`IAuditableItemStreamEntryList`\>
561
+ `Promise`\<\{ `entries`: `IAuditableItemStreamEntryList`; `cursor?`: `string`; \}\>
529
562
 
530
563
  The stream and entries if found.
531
564
 
@@ -539,19 +572,19 @@ NotFoundError if the stream is not found.
539
572
 
540
573
  ***
541
574
 
542
- ### getEntryObjects()
575
+ ### getEntryObjects() {#getentryobjects}
543
576
 
544
- > **getEntryObjects**(`id`, `options?`): `Promise`\<`IAuditableItemStreamEntryObjectList`\>
577
+ > **getEntryObjects**(`id?`, `options?`): `Promise`\<\{ `entries`: `IAuditableItemStreamEntryObjectList`; `cursor?`: `string`; \}\>
545
578
 
546
579
  Get the entry objects for the stream.
547
580
 
548
581
  #### Parameters
549
582
 
550
- ##### id
583
+ ##### id?
551
584
 
552
585
  `string`
553
586
 
554
- The id of the stream to get.
587
+ The id of the stream to get, if undefined returns all matching entries.
555
588
 
556
589
  ##### options?
557
590
 
@@ -589,7 +622,7 @@ Retrieve the entries in ascending/descending time order, defaults to Ascending.
589
622
 
590
623
  #### Returns
591
624
 
592
- `Promise`\<`IAuditableItemStreamEntryObjectList`\>
625
+ `Promise`\<\{ `entries`: `IAuditableItemStreamEntryObjectList`; `cursor?`: `string`; \}\>
593
626
 
594
627
  The stream and entries if found.
595
628
 
@@ -600,33 +633,3 @@ NotFoundError if the stream is not found.
600
633
  #### Implementation of
601
634
 
602
635
  `IAuditableItemStreamComponent.getEntryObjects`
603
-
604
- ***
605
-
606
- ### removeVerifiable()
607
-
608
- > **removeVerifiable**(`id`): `Promise`\<`void`\>
609
-
610
- Remove the verifiable storage for the stream and entries, not supported on client.
611
-
612
- #### Parameters
613
-
614
- ##### id
615
-
616
- `string`
617
-
618
- The id of the stream to remove the storage from.
619
-
620
- #### Returns
621
-
622
- `Promise`\<`void`\>
623
-
624
- Nothing.
625
-
626
- #### Throws
627
-
628
- NotFoundError if the vertex is not found.
629
-
630
- #### Implementation of
631
-
632
- `IAuditableItemStreamComponent.removeVerifiable`
package/locales/en.json CHANGED
@@ -1,7 +1 @@
1
- {
2
- "error": {
3
- "auditableItemStreamRestClient": {
4
- "notSupportedOnClient": "The method \"{methodName}\" is not supported on the REST client, it can only be used on a server side component"
5
- }
6
- }
7
- }
1
+ {}
package/package.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "name": "@twin.org/auditable-item-stream-rest-client",
3
- "version": "0.0.3-next.2",
4
- "description": "Auditable Item Stream contract implementation which can connect to REST endpoints",
3
+ "version": "0.0.3-next.21",
4
+ "description": "HTTP client for interacting with auditable stream service endpoints.",
5
5
  "repository": {
6
6
  "type": "git",
7
- "url": "git+https://github.com/twinfoundation/auditable-item-stream.git",
7
+ "url": "git+https://github.com/iotaledger/twin-auditable-item-stream.git",
8
8
  "directory": "packages/auditable-item-stream-rest-client"
9
9
  },
10
10
  "author": "martyn.janes@iota.org",
@@ -16,7 +16,7 @@
16
16
  "dependencies": {
17
17
  "@twin.org/api-core": "next",
18
18
  "@twin.org/api-models": "next",
19
- "@twin.org/auditable-item-stream-models": "0.0.3-next.2",
19
+ "@twin.org/auditable-item-stream-models": "0.0.3-next.21",
20
20
  "@twin.org/core": "next",
21
21
  "@twin.org/data-json-ld": "next",
22
22
  "@twin.org/entity": "next",
@@ -48,7 +48,7 @@
48
48
  "auditable-item-stream"
49
49
  ],
50
50
  "bugs": {
51
- "url": "git+https://github.com/twinfoundation/auditable-item-stream/issues"
51
+ "url": "git+https://github.com/iotaledger/twin-auditable-item-stream/issues"
52
52
  },
53
53
  "homepage": "https://twindev.org"
54
54
  }