@twin.org/synchronised-storage-service 0.0.3-next.9 → 0.9.0

package/docs/examples.md

@@ -1 +1,80 @@
-# @twin.org/synchronised-storage-service - Examples
+# Synchronised Storage Service Examples
+
+These examples show common node-side synchronisation flows, from startup and scheduling to trusted key exchange and inbound change application.
+
+## SynchronisedStorageService
+
+```typescript
+import { SynchronisedStorageService } from '@twin.org/synchronised-storage-service';
+
+const service = new SynchronisedStorageService({
+  loggingComponentType: 'logging',
+  eventBusComponentType: 'event-bus',
+  taskSchedulerComponentType: 'task-scheduler',
+  config: {
+    verifiableStorageKeyId: 'devnet',
+    entityUpdateIntervalMinutes: 2,
+    consolidationIntervalMinutes: 30,
+    consolidationBatchSize: 200,
+    maxConsolidations: 8,
+    blobStorageEncryptionKeyId: 'sync-blob-key'
+  }
+});
+
+console.log(service.className()); // SynchronisedStorageService
+
+await service.start('logging');
+await service.stop('logging');
+```
+
+```typescript
+import { SynchronisedStorageService } from '@twin.org/synchronised-storage-service';
+
+const trustedService = new SynchronisedStorageService({
+  config: {
+    verifiableStorageKeyId: 'mainnet',
+    blobStorageEncryptionKeyId: 'sync-blob-key'
+  }
+});
+
+const trustPayload = 'eyJhbGciOiJFZERTQSJ9.trusted-node.signature';
+const decryptionKey = await trustedService.getDecryptionKey(trustPayload);
+
+console.log(decryptionKey.length); // 44
+```
+
+```typescript
+import {
+  SynchronisedStorageContexts,
+  SynchronisedStorageTypes,
+  SyncChangeOperation,
+  type ISyncChangeSet
+} from '@twin.org/synchronised-storage-models';
+import { SynchronisedStorageService } from '@twin.org/synchronised-storage-service';
+
+const trustedService = new SynchronisedStorageService({
+  config: {
+    verifiableStorageKeyId: 'testnet',
+    blobStorageEncryptionKeyId: 'sync-blob-key'
+  }
+});
+
+const changeSet: ISyncChangeSet = {
+  '@context': SynchronisedStorageContexts.Context,
+  type: SynchronisedStorageTypes.ChangeSet,
+  id: 'changeset-remote-7',
+  storageKey: 'profile',
+  dateCreated: '2026-03-10T12:00:00.000Z',
+  dateModified: '2026-03-10T12:00:00.000Z',
+  nodeIdentity: 'did:iota:node-9',
+  changes: [
+    {
+      operation: SyncChangeOperation.Delete,
+      id: 'profile-7'
+    }
+  ]
+};
+
+const trustPayload = 'eyJhbGciOiJFZERTQSJ9.remote-node.signature';
+await trustedService.syncChangeSet(changeSet, trustPayload);
+```

package/docs/open-api/spec.json

@@ -228,6 +228,7 @@
 	"components": {
 		"schemas": {
 			"Error": {
+				"description": "Model to describe serialized error.",
 				"type": "object",
 				"properties": {
 					"name": {
@@ -236,7 +237,7 @@
 					},
 					"message": {
 						"type": "string",
-						"description": "The message for the error."
+						"description": "The message for the error as an i18n key."
 					},
 					"source": {
 						"type": "string",
@@ -258,10 +259,10 @@
 				"required": [
 					"name",
 					"message"
-				],
-				"description": "Model to describe serialized error."
+				]
 			},
 			"SyncChange": {
+				"description": "The object definition for a sync change.",
 				"type": "object",
 				"properties": {
 					"operation": {
@@ -278,34 +279,30 @@
 				"required": [
 					"operation",
 					"id"
-				],
-				"description": "The object definition for a sync change."
+				]
 			},
 			"SyncChangeOperation": {
+				"description": "The operations for a change",
 				"anyOf": [
 					{
-						"type": "string",
 						"const": "set",
 						"description": "An item was set in the storage."
 					},
 					{
-						"type": "string",
 						"const": "delete",
 						"description": "An item was deleted from the storage."
 					}
-				],
-				"description": "The operations for a change.   The operations for a change"
+				]
 			},
 			"SyncChangeSet": {
+				"description": "The object definition for a sync change set.",
 				"type": "object",
 				"properties": {
 					"@context": {
-						"type": "string",
 						"const": "https://schema.twindev.org/synchronised-storage/",
 						"description": "The LD Context for the change set."
 					},
 					"type": {
-						"type": "string",
 						"const": "ChangeSet",
 						"description": "The LD Type for the change set."
 					},
@@ -315,26 +312,26 @@
 					},
 					"storageKey": {
 						"type": "string",
-						"description": "The storage key of the change set. This is used to identify the entities being synchronised. json-ld type:schema:identifier"
+						"description": "The storage key of the change set. This is used to identify the entities being synchronised."
 					},
 					"dateCreated": {
 						"type": "string",
-						"description": "The date the change set was created. json-ld namespace:schema"
+						"description": "The date the change set was created."
 					},
 					"dateModified": {
 						"type": "string",
-						"description": "The date the change set was last modified. json-ld namespace:schema"
+						"description": "The date the change set was last modified."
 					},
 					"nodeIdentity": {
 						"type": "string",
-						"description": "The identity of the node that created the change set. json-ld namespace:twin-common"
+						"description": "The identity of the node that created the change set."
 					},
 					"changes": {
 						"type": "array",
 						"items": {
 							"$ref": "#/components/schemas/SyncChange"
 						},
-						"description": "The changes to apply after a snapshot. json-ld type:json"
+						"description": "The changes to apply after a snapshot."
 					}
 				},
 				"required": [
@@ -346,8 +343,7 @@
 					"dateModified",
 					"nodeIdentity",
 					"changes"
-				],
-				"description": "The object definition for a sync change set."
+				]
 			},
 			"SyncDecryptionKeyResponse": {
 				"type": "object",
@@ -363,17 +359,17 @@
 				"description": "The body of the response."
 			},
 			"SynchronisedEntityCore": {
+				"description": "The base definition for synchronised entries.",
 				"type": "object",
 				"properties": {
 					"dateModified": {
 						"type": "string",
-						"description": "The date the entry was modified. json-ld namespace:schema"
+						"description": "The date the entry was modified."
 					}
 				},
 				"required": [
 					"dateModified"
-				],
-				"description": "The base definition for synchronised entries."
+				]
 			}
 		},
 		"securitySchemes": {

package/docs/reference/classes/SyncSnapshotEntry.md

@@ -14,7 +14,7 @@ Class representing an entry for the sync snapshot.
 
 ## Properties
 
-### id
+### id {#id}
 
 > **id**: `string`
 
@@ -22,7 +22,7 @@ The id for the snapshot.
 
 ***
 
-### version
+### version {#version}
 
 > **version**: `string`
 
@@ -30,7 +30,7 @@ The version for the snapshot.
 
 ***
 
-### storageKey
+### storageKey {#storagekey}
 
 > **storageKey**: `string`
 
@@ -38,7 +38,7 @@ The storage key for the snapshot i.e. which entity is being synchronized.
 
 ***
 
-### dateCreated
+### dateCreated {#datecreated}
 
 > **dateCreated**: `string`
 
@@ -46,7 +46,7 @@ The date the snapshot was created.
 
 ***
 
-### dateModified
+### dateModified {#datemodified}
 
 > **dateModified**: `string`
 
@@ -54,7 +54,7 @@ The date the snapshot was last modified.
 
 ***
 
-### isLocal
+### isLocal {#islocal}
 
 > **isLocal**: `boolean`
 
@@ -62,7 +62,7 @@ The flag to determine if this is the snapshot is the local one containing change
 
 ***
 
-### isConsolidated
+### isConsolidated {#isconsolidated}
 
 > **isConsolidated**: `boolean`
 
@@ -70,7 +70,7 @@ The flag to determine if this is a consolidated snapshot.
 
 ***
 
-### epoch
+### epoch {#epoch}
 
 > **epoch**: `number`
 
@@ -78,16 +78,16 @@ The epoch for the changeset.
 
 ***
 
-### changeSetStorageIds?
+### changeSetStorageIds? {#changesetstorageids}
 
-> `optional` **changeSetStorageIds**: `string`[]
+> `optional` **changeSetStorageIds?**: `string`[]
 
 The ids of the storage for the change sets in the snapshot, if this is not a local snapshot.
 
 ***
 
-### changes?
+### changes? {#changes}
 
-> `optional` **changes**: `ISyncChange`[]
+> `optional` **changes?**: `ISyncChange`[]
 
 The changes that were made in this snapshot, if this is a local snapshot.

package/docs/reference/classes/SynchronisedStorageService.md

@@ -28,7 +28,7 @@ The options for the service.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -36,7 +36,7 @@ Runtime name for the class.
 
 ## Methods
 
-### className()
+### className() {#classname}
 
 > **className**(): `string`
 
@@ -54,7 +54,7 @@ The class name of the component.
 
 ***
 
-### start()
+### start() {#start}
 
 > **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
 
@@ -72,7 +72,7 @@ The node logging component type.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the service is started and all event bus subscriptions are active.
 
 #### Implementation of
 
@@ -80,7 +80,7 @@ Nothing.
 
 ***
 
-### stop()
+### stop() {#stop}
 
 > **stop**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
 
@@ -98,7 +98,7 @@ The node logging component type.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when all scheduled tasks are removed and storage keys are deactivated.
 
 #### Implementation of
 
@@ -106,7 +106,7 @@ Nothing.
 
 ***
 
-### getDecryptionKey()
+### getDecryptionKey() {#getdecryptionkey}
 
 > **getDecryptionKey**(`trustPayload`): `Promise`\<`string`\>
 
@@ -133,7 +133,7 @@ The decryption key.
 
 ***
 
-### syncChangeSet()
+### syncChangeSet() {#syncchangeset}
 
 > **syncChangeSet**(`syncChangeSet`, `trustPayload`): `Promise`\<`void`\>
 
@@ -157,7 +157,7 @@ Trust payload to verify the requesters identity.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the change set has been applied and the sync state updated.
 
 #### Implementation of
 

package/docs/reference/interfaces/ISyncPointerStore.md

@@ -4,7 +4,7 @@ The object definition for the sync pointer store.
 
 ## Properties
 
-### version
+### version {#version}
 
 > **version**: `string`
 
@@ -12,7 +12,7 @@ The version of the sync pointer store.
 
 ***
 
-### syncPointers
+### syncPointers {#syncpointers}
 
 > **syncPointers**: `object`
 

package/docs/reference/interfaces/ISyncSnapshot.md

@@ -4,7 +4,7 @@ The object definition for a sync snapshot.
 
 ## Properties
 
-### version
+### version {#version}
 
 > **version**: `string`
 
@@ -12,7 +12,7 @@ The version of the sync state.
 
 ***
 
-### id
+### id {#id}
 
 > **id**: `string`
 
@@ -20,7 +20,7 @@ The id of the snapshot.
 
 ***
 
-### dateCreated
+### dateCreated {#datecreated}
 
 > **dateCreated**: `string`
 
@@ -28,7 +28,7 @@ The date the snapshot was created.
 
 ***
 
-### dateModified
+### dateModified {#datemodified}
 
 > **dateModified**: `string`
 
@@ -36,7 +36,7 @@ The date the snapshot was last modified.
 
 ***
 
-### isConsolidated
+### isConsolidated {#isconsolidated}
 
 > **isConsolidated**: `boolean`
 
@@ -44,7 +44,7 @@ Is this a consolidated snapshot?
 
 ***
 
-### epoch
+### epoch {#epoch}
 
 > **epoch**: `number`
 
@@ -52,7 +52,7 @@ The epoch of the snapshot.
 
 ***
 
-### changeSetStorageIds
+### changeSetStorageIds {#changesetstorageids}
 
 > **changeSetStorageIds**: `string`[]
 

package/docs/reference/interfaces/ISyncState.md

@@ -4,7 +4,7 @@ The object definition for a sync state.
 
 ## Properties
 
-### version
+### version {#version}
 
 > **version**: `string`
 
@@ -12,7 +12,7 @@ The version of the sync state.
 
 ***
 
-### storageKey
+### storageKey {#storagekey}
 
 > **storageKey**: `string`
 
@@ -20,7 +20,7 @@ The storage type contained in the sync state.
 
 ***
 
-### snapshots
+### snapshots {#snapshots}
 
 > **snapshots**: [`ISyncSnapshot`](ISyncSnapshot.md)[]
 

package/docs/reference/interfaces/ISynchronisedStorageServiceConfig.md

@@ -4,9 +4,9 @@ Configuration for the Synchronised Storage Service.
 
 ## Properties
 
-### entityUpdateIntervalMinutes?
+### entityUpdateIntervalMinutes? {#entityupdateintervalminutes}
 
-> `optional` **entityUpdateIntervalMinutes**: `number`
+> `optional` **entityUpdateIntervalMinutes?**: `number`
 
 How often to check for entity updates in minutes.
 
@@ -18,9 +18,9 @@ How often to check for entity updates in minutes.
 
 ***
 
-### consolidationIntervalMinutes?
+### consolidationIntervalMinutes? {#consolidationintervalminutes}
 
-> `optional` **consolidationIntervalMinutes**: `number`
+> `optional` **consolidationIntervalMinutes?**: `number`
 
 Interval to perform consolidation of changesets, only used if this is a trusted node.
 
@@ -32,9 +32,9 @@ Interval to perform consolidation of changesets, only used if this is a trusted
 
 ***
 
-### consolidationBatchSize?
+### consolidationBatchSize? {#consolidationbatchsize}
 
-> `optional` **consolidationBatchSize**: `number`
+> `optional` **consolidationBatchSize?**: `number`
 
 The number of entities to process in a single consolidation batch, only used if this is a trusted node.
 
@@ -46,9 +46,9 @@ The number of entities to process in a single consolidation batch, only used if
 
 ***
 
-### maxConsolidations?
+### maxConsolidations? {#maxconsolidations}
 
-> `optional` **maxConsolidations**: `number`
+> `optional` **maxConsolidations?**: `number`
 
 The maximum number of consolidations to keep in storage, only used if this is a trusted node.
 
@@ -60,9 +60,9 @@ The maximum number of consolidations to keep in storage, only used if this is a
 
 ***
 
-### blobStorageEncryptionKeyId?
+### blobStorageEncryptionKeyId? {#blobstorageencryptionkeyid}
 
-> `optional` **blobStorageEncryptionKeyId**: `string`
+> `optional` **blobStorageEncryptionKeyId?**: `string`
 
 The encryption key id from the vault to use for blob storage, only required for trusted nodes, untrusted nodes will request the key.
 
@@ -74,7 +74,7 @@ synchronised-storage-blob-encryption-key
 
 ***
 
-### verifiableStorageKeyId
+### verifiableStorageKeyId {#verifiablestoragekeyid}
 
 > **verifiableStorageKeyId**: `string`
 
@@ -89,8 +89,8 @@ local
 
 ***
 
-### overrideTrustGeneratorType?
+### overrideTrustGeneratorType? {#overridetrustgeneratortype}
 
-> `optional` **overrideTrustGeneratorType**: `string`
+> `optional` **overrideTrustGeneratorType?**: `string`
 
 Override the default trust generator.

package/docs/reference/interfaces/ISynchronisedStorageServiceConstructorOptions.md

@@ -4,33 +4,33 @@ Options for the Synchronised Storage Service constructor.
 
 ## Properties
 
-### loggingComponentType?
+### loggingComponentType? {#loggingcomponenttype}
 
-> `optional` **loggingComponentType**: `string`
+> `optional` **loggingComponentType?**: `string`
 
 The logging component.
 
 ***
 
-### eventBusComponentType?
+### eventBusComponentType? {#eventbuscomponenttype}
 
-> `optional` **eventBusComponentType**: `string`
+> `optional` **eventBusComponentType?**: `string`
 
 The event bus component type.
 
 ***
 
-### vaultConnectorType?
+### vaultConnectorType? {#vaultconnectortype}
 
-> `optional` **vaultConnectorType**: `string`
+> `optional` **vaultConnectorType?**: `string`
 
 The vault connector type.
 
 ***
 
-### syncSnapshotStorageConnectorType?
+### syncSnapshotStorageConnectorType? {#syncsnapshotstorageconnectortype}
 
-> `optional` **syncSnapshotStorageConnectorType**: `string`
+> `optional` **syncSnapshotStorageConnectorType?**: `string`
 
 The entity storage connector type to use for sync snapshots.
 
@@ -42,9 +42,9 @@ sync-snapshot-entry
 
 ***
 
-### blobStorageConnectorType?
+### blobStorageConnectorType? {#blobstorageconnectortype}
 
-> `optional` **blobStorageConnectorType**: `string`
+> `optional` **blobStorageConnectorType?**: `string`
 
 The blob storage connector used for remote sync state.
 
@@ -56,9 +56,9 @@ blob-storage
 
 ***
 
-### verifiableStorageConnectorType?
+### verifiableStorageConnectorType? {#verifiablestorageconnectortype}
 
-> `optional` **verifiableStorageConnectorType**: `string`
+> `optional` **verifiableStorageConnectorType?**: `string`
 
 The verifiable storage connector type to use for decentralised state.
 
@@ -70,9 +70,9 @@ verifiable-storage
 
 ***
 
-### taskSchedulerComponentType?
+### taskSchedulerComponentType? {#taskschedulercomponenttype}
 
-> `optional` **taskSchedulerComponentType**: `string`
+> `optional` **taskSchedulerComponentType?**: `string`
 
 The task scheduler component.
 
@@ -84,9 +84,9 @@ task-scheduler
 
 ***
 
-### trustComponentType?
+### trustComponentType? {#trustcomponenttype}
 
-> `optional` **trustComponentType**: `string`
+> `optional` **trustComponentType?**: `string`
 
 The type of the trust component.
 
@@ -98,16 +98,16 @@ trust
 
 ***
 
-### trustedSynchronisedStorageComponentType?
+### trustedSynchronisedStorageComponentType? {#trustedsynchronisedstoragecomponenttype}
 
-> `optional` **trustedSynchronisedStorageComponentType**: `string`
+> `optional` **trustedSynchronisedStorageComponentType?**: `string`
 
 The synchronised entity storage component type to use if this node is not trusted.
 If this is set, this node uses it as the trusted node to store changesets.
 
 ***
 
-### config
+### config {#config}
 
 > **config**: [`ISynchronisedStorageServiceConfig`](ISynchronisedStorageServiceConfig.md)
 

package/docs/reference/variables/restEntryPoints.md

@@ -1,3 +1,5 @@
 # Variable: restEntryPoints
 
 > `const` **restEntryPoints**: `IRestRouteEntryPoint`[]
+
+REST entry points for the synchronised storage service.