@twin.org/synchronised-storage-models 0.0.1-next.3 → 0.0.1-next.5

package/dist/cjs/index.cjs

@@ -40,6 +40,10 @@ const SynchronisedStorageTopics = {
      * A response to a local item request.
      */
     LocalItemResponse: "synchronised-storage:local-item-response",
+    /**
+     * Reset the storage.
+     */
+    Reset: "synchronised-storage:reset",
     /**
      * A request has been made for a batch.
      */
@@ -58,5 +62,27 @@ const SynchronisedStorageTopics = {
     RemoteItemRemove: "synchronised-storage:remote-item-remove"
 };
 
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The mode to determine how node identities are matched.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const SyncNodeIdentityMode = {
+    /**
+     * Match the local node identity.
+     */
+    Local: "local",
+    /**
+     * Match all but the local node identity.
+     */
+    Remote: "remote",
+    /**
+     * All match both local and remote entities.
+     */
+    All: "all"
+};
+
 exports.SyncChangeOperation = SyncChangeOperation;
+exports.SyncNodeIdentityMode = SyncNodeIdentityMode;
 exports.SynchronisedStorageTopics = SynchronisedStorageTopics;

package/dist/esm/index.mjs

@@ -38,6 +38,10 @@ const SynchronisedStorageTopics = {
      * A response to a local item request.
      */
     LocalItemResponse: "synchronised-storage:local-item-response",
+    /**
+     * Reset the storage.
+     */
+    Reset: "synchronised-storage:reset",
     /**
      * A request has been made for a batch.
      */
@@ -56,4 +60,25 @@ const SynchronisedStorageTopics = {
     RemoteItemRemove: "synchronised-storage:remote-item-remove"
 };
 
-export { SyncChangeOperation, SynchronisedStorageTopics };
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The mode to determine how node identities are matched.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const SyncNodeIdentityMode = {
+    /**
+     * Match the local node identity.
+     */
+    Local: "local",
+    /**
+     * Match all but the local node identity.
+     */
+    Remote: "remote",
+    /**
+     * All match both local and remote entities.
+     */
+    All: "all"
+};
+
+export { SyncChangeOperation, SyncNodeIdentityMode, SynchronisedStorageTopics };

package/dist/types/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./models/api/ISyncChangeSetRequest";
+export * from "./models/api/ISyncDecryptionKeyRequest";
+export * from "./models/api/ISyncDecryptionKeyResponse";
 export * from "./models/eventBus/ISyncBatchRequest";
 export * from "./models/eventBus/ISyncBatchResponse";
 export * from "./models/eventBus/ISyncItemChange";
@@ -7,7 +9,11 @@ export * from "./models/eventBus/ISyncItemRequest";
 export * from "./models/eventBus/ISyncItemResponse";
 export * from "./models/eventBus/ISyncItemSet";
 export * from "./models/eventBus/ISyncRegisterStorageKey";
+export * from "./models/eventBus/ISyncReset";
 export * from "./models/eventBus/syncChangeOperation";
+export * from "./models/ISyncChange";
+export * from "./models/ISyncChangeSet";
 export * from "./models/ISynchronisedEntity";
 export * from "./models/ISynchronisedStorageComponent";
 export * from "./models/synchronisedStorageTopics";
+export * from "./models/syncNodeIdentityMode";

package/dist/types/models/ISyncChange.d.ts

@@ -0,0 +1,19 @@
+import type { SyncChangeOperation } from "./eventBus/syncChangeOperation";
+import type { ISynchronisedEntity } from "./ISynchronisedEntity";
+/**
+ * The object definition for a sync change.
+ */
+export interface ISyncChange<T extends ISynchronisedEntity = ISynchronisedEntity> {
+    /**
+     * Operation.
+     */
+    operation: SyncChangeOperation;
+    /**
+     * The item id.
+     */
+    id: string;
+    /**
+     * The entity to set.
+     */
+    entity?: Omit<T, "id" | "nodeIdentity">;
+}

package/dist/types/models/ISyncChangeSet.d.ts

@@ -0,0 +1,36 @@
+import type { IProof } from "@twin.org/standards-w3c-did";
+import type { ISyncChange } from "./ISyncChange";
+import type { ISynchronisedEntity } from "./ISynchronisedEntity";
+/**
+ * The object definition for a sync change set.
+ */
+export interface ISyncChangeSet<T extends ISynchronisedEntity = ISynchronisedEntity> {
+    /**
+     * The id of the change set.
+     */
+    id: string;
+    /**
+     * The date the change set was created.
+     */
+    dateCreated: string;
+    /**
+     * The storage key of the change set. This is used to identify the entities being synchronised.
+     */
+    storageKey: string;
+    /**
+     * The date the change set was last modified.
+     */
+    dateModified: string;
+    /**
+     * The changes to apply after a snapshot.
+     */
+    changes: ISyncChange<T>[];
+    /**
+     * The identity of the node that created the change set.
+     */
+    nodeIdentity: string;
+    /**
+     * The proof for the change set.
+     */
+    proof?: IProof;
+}

package/dist/types/models/ISynchronisedEntity.d.ts

@@ -2,6 +2,10 @@
  * The base definition for synchronised entries.
  */
 export interface ISynchronisedEntity {
+    /**
+     * The id of the entry.
+     */
+    id: string;
     /**
      * The date the entry was modified
      */

package/dist/types/models/ISynchronisedStorageComponent.d.ts

@@ -1,12 +1,22 @@
 import type { IComponent } from "@twin.org/core";
+import type { IProof } from "@twin.org/standards-w3c-did";
+import type { ISyncChangeSet } from "./ISyncChangeSet";
 /**
  * Class for performing synchronised storage operations.
  */
 export interface ISynchronisedStorageComponent extends IComponent {
     /**
-     * Synchronise a complete set of changes, assumes this is a trusted node.
-     * @param changeSetStorageId The id of the change set to synchronise in blob storage.
+     * Get the decryption key for the synchronised storage.
+     * This is used to decrypt the data stored in the synchronised storage.
+     * @param nodeIdentity The identity of the node requesting the decryption key.
+     * @param proof The proof of the request so we know the request is from the specified node.
+     * @returns The decryption key.
+     */
+    getDecryptionKey(nodeIdentity: string, proof: IProof): Promise<string>;
+    /**
+     * Synchronise a set of changes from an untrusted node, assumes this is a trusted node.
+     * @param syncChangeSet The change set to synchronise.
      * @returns Nothing.
      */
-    syncChangeSet(changeSetStorageId: string): Promise<void>;
+    syncChangeSet(syncChangeSet: ISyncChangeSet): Promise<void>;
 }

package/dist/types/models/api/ISyncChangeSetRequest.d.ts

@@ -1,14 +1,10 @@
+import type { ISyncChangeSet } from "../ISyncChangeSet";
 /**
  * Request a trusted node to perform a sync request for a changeset.
  */
 export interface ISyncChangeSetRequest {
     /**
-     * The query parameters.
+     * The body of the request.
      */
-    query: {
-        /**
-         * The storage id of the changeset.
-         */
-        changeSetStorageId: string;
-    };
+    body: ISyncChangeSet;
 }

package/dist/types/models/api/ISyncDecryptionKeyRequest.d.ts

@@ -0,0 +1,19 @@
+import type { IProof } from "@twin.org/standards-w3c-did";
+/**
+ * Request for the decryption key for the synchronised storage.
+ */
+export interface ISyncDecryptionKeyRequest {
+    /**
+     * The body of the request.
+     */
+    body: {
+        /**
+         * The identity of the node making the request.
+         */
+        nodeIdentity: string;
+        /**
+         * The proof of the request.
+         */
+        proof: IProof;
+    };
+}

package/dist/types/models/api/ISyncDecryptionKeyResponse.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Response to a request for the decryption key for the synchronised storage.
+ */
+export interface ISyncDecryptionKeyResponse {
+    /**
+     * The body of the response.
+     */
+    body: {
+        /**
+         * The decryption key for the synchronised storage as base64.
+         */
+        decryptionKey: string;
+    };
+}

package/dist/types/models/eventBus/ISyncBatchRequest.d.ts

@@ -1,3 +1,4 @@
+import type { SyncNodeIdentityMode } from "../syncNodeIdentityMode";
 /**
  * Request for a local batch.
  */
@@ -10,4 +11,8 @@ export interface ISyncBatchRequest {
      * The size of the batch.
      */
     batchSize: number;
+    /**
+     * Determines which entries are required, for local it will match the nodeIdentity, for remote it will not include matching nodeIdentity, for all it will include all entries.
+     */
+    requestMode: SyncNodeIdentityMode;
 }

package/dist/types/models/eventBus/ISyncBatchResponse.d.ts

@@ -7,10 +7,6 @@ export interface ISyncBatchResponse<T extends ISynchronisedEntity> {
      * The key of the storage for the entities in the batch.
      */
     storageKey: string;
-    /**
-     * The primary key of the entity in the sync item response.
-     */
-    primaryKey: keyof T;
     /**
      * The entities in the batch.
      */

package/dist/types/models/eventBus/ISyncItemChange.d.ts

@@ -11,6 +11,10 @@ export interface ISyncItemChange {
      * The operation being performed on the item.
      */
     operation: SyncChangeOperation;
+    /**
+     * The node performing the operation.
+     */
+    nodeIdentity: string;
     /**
      * The id of the item being changed.
      */

package/dist/types/models/eventBus/ISyncItemRemove.d.ts

@@ -6,6 +6,10 @@ export interface ISyncItemRemove {
      * The key of the storage being removed.
      */
     storageKey: string;
+    /**
+     * The node identity of the entity being removed.
+     */
+    nodeIdentity: string;
     /**
      * The entity being removed from the item set.
      */

package/dist/types/models/eventBus/ISyncReset.d.ts

@@ -0,0 +1,14 @@
+import type { SyncNodeIdentityMode } from "../syncNodeIdentityMode";
+/**
+ * Request to reset the local storage.
+ */
+export interface ISyncReset {
+    /**
+     * The key of the storage for the entities in the batch.
+     */
+    storageKey: string;
+    /**
+     * Reset mode, this will use the nodeIdentity in the entities to determine which are local/remote.
+     */
+    resetMode: SyncNodeIdentityMode;
+}

package/dist/types/models/syncNodeIdentityMode.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The mode to determine how node identities are matched.
+ */
+export declare const SyncNodeIdentityMode: {
+    /**
+     * Match the local node identity.
+     */
+    readonly Local: "local";
+    /**
+     * Match all but the local node identity.
+     */
+    readonly Remote: "remote";
+    /**
+     * All match both local and remote entities.
+     */
+    readonly All: "all";
+};
+/**
+ * The mode to determine how node identities are matched.
+ */
+export type SyncNodeIdentityMode = (typeof SyncNodeIdentityMode)[keyof typeof SyncNodeIdentityMode];

package/dist/types/models/synchronisedStorageTopics.d.ts

@@ -18,6 +18,10 @@ export declare const SynchronisedStorageTopics: {
      * A response to a local item request.
      */
     readonly LocalItemResponse: "synchronised-storage:local-item-response";
+    /**
+     * Reset the storage.
+     */
+    readonly Reset: "synchronised-storage:reset";
     /**
      * A request has been made for a batch.
      */

package/docs/changelog.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.0.1-next.5](https://github.com/twinfoundation/synchronised-storage/compare/synchronised-storage-models-v0.0.1-next.4...synchronised-storage-models-v0.0.1-next.5) (2025-08-11)
+
+
+### Features
+
+* additional node identity checks ([76257c4](https://github.com/twinfoundation/synchronised-storage/commit/76257c4173303d484391f71f581fd0e214204029))
+
+
+### Bug Fixes
+
+* missing dependency ([cf4427e](https://github.com/twinfoundation/synchronised-storage/commit/cf4427edf6668b90aae9a9c1faafff13dffc2fc7))
+
+## [0.0.1-next.4](https://github.com/twinfoundation/synchronised-storage/compare/synchronised-storage-models-v0.0.1-next.3...synchronised-storage-models-v0.0.1-next.4) (2025-08-08)
+
+
+### Features
+
+* blob storage connector instead of component ([#7](https://github.com/twinfoundation/synchronised-storage/issues/7)) ([ea27241](https://github.com/twinfoundation/synchronised-storage/commit/ea27241cf0810b52ab7a6be7346809d127b7109a))
+
 ## [0.0.1-next.3](https://github.com/twinfoundation/synchronised-storage/compare/synchronised-storage-models-v0.0.1-next.2...synchronised-storage-models-v0.0.1-next.3) (2025-07-25)
 
 

package/docs/reference/index.md

@@ -2,9 +2,13 @@
 
 ## Interfaces
 
+- [ISyncChange](interfaces/ISyncChange.md)
+- [ISyncChangeSet](interfaces/ISyncChangeSet.md)
 - [ISynchronisedEntity](interfaces/ISynchronisedEntity.md)
 - [ISynchronisedStorageComponent](interfaces/ISynchronisedStorageComponent.md)
 - [ISyncChangeSetRequest](interfaces/ISyncChangeSetRequest.md)
+- [ISyncDecryptionKeyRequest](interfaces/ISyncDecryptionKeyRequest.md)
+- [ISyncDecryptionKeyResponse](interfaces/ISyncDecryptionKeyResponse.md)
 - [ISyncBatchRequest](interfaces/ISyncBatchRequest.md)
 - [ISyncBatchResponse](interfaces/ISyncBatchResponse.md)
 - [ISyncItemChange](interfaces/ISyncItemChange.md)
@@ -13,13 +17,16 @@
 - [ISyncItemResponse](interfaces/ISyncItemResponse.md)
 - [ISyncItemSet](interfaces/ISyncItemSet.md)
 - [ISyncRegisterStorageKey](interfaces/ISyncRegisterStorageKey.md)
+- [ISyncReset](interfaces/ISyncReset.md)
 
 ## Type Aliases
 
 - [SyncChangeOperation](type-aliases/SyncChangeOperation.md)
+- [SyncNodeIdentityMode](type-aliases/SyncNodeIdentityMode.md)
 - [SynchronisedStorageTopics](type-aliases/SynchronisedStorageTopics.md)
 
 ## Variables
 
 - [SyncChangeOperation](variables/SyncChangeOperation.md)
+- [SyncNodeIdentityMode](variables/SyncNodeIdentityMode.md)
 - [SynchronisedStorageTopics](variables/SynchronisedStorageTopics.md)

package/docs/reference/interfaces/ISyncBatchRequest.md

@@ -17,3 +17,11 @@ The key of the storage for the entities in the batch.
 > **batchSize**: `number`
 
 The size of the batch.
+
+***
+
+### requestMode
+
+> **requestMode**: [`SyncNodeIdentityMode`](../type-aliases/SyncNodeIdentityMode.md)
+
+Determines which entries are required, for local it will match the nodeIdentity, for remote it will not include matching nodeIdentity, for all it will include all entries.

package/docs/reference/interfaces/ISyncBatchResponse.md

@@ -18,14 +18,6 @@ The key of the storage for the entities in the batch.
 
 ***
 
-### primaryKey
-
-> **primaryKey**: keyof `T`
-
-The primary key of the entity in the sync item response.
-
-***
-
 ### entities
 
 > **entities**: `T`[]

package/docs/reference/interfaces/ISyncChange.md

@@ -0,0 +1,33 @@
+# Interface: ISyncChange\<T\>
+
+The object definition for a sync change.
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`ISynchronisedEntity`](ISynchronisedEntity.md) = [`ISynchronisedEntity`](ISynchronisedEntity.md)
+
+## Properties
+
+### operation
+
+> **operation**: [`SyncChangeOperation`](../type-aliases/SyncChangeOperation.md)
+
+Operation.
+
+***
+
+### id
+
+> **id**: `string`
+
+The item id.
+
+***
+
+### entity?
+
+> `optional` **entity**: `Omit`\<`T`, `"id"` \| `"nodeIdentity"`\>
+
+The entity to set.

package/docs/reference/interfaces/ISyncChangeSet.md

@@ -0,0 +1,65 @@
+# Interface: ISyncChangeSet\<T\>
+
+The object definition for a sync change set.
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`ISynchronisedEntity`](ISynchronisedEntity.md) = [`ISynchronisedEntity`](ISynchronisedEntity.md)
+
+## Properties
+
+### id
+
+> **id**: `string`
+
+The id of the change set.
+
+***
+
+### dateCreated
+
+> **dateCreated**: `string`
+
+The date the change set was created.
+
+***
+
+### storageKey
+
+> **storageKey**: `string`
+
+The storage key of the change set. This is used to identify the entities being synchronised.
+
+***
+
+### dateModified
+
+> **dateModified**: `string`
+
+The date the change set was last modified.
+
+***
+
+### changes
+
+> **changes**: [`ISyncChange`](ISyncChange.md)\<`T`\>[]
+
+The changes to apply after a snapshot.
+
+***
+
+### nodeIdentity
+
+> **nodeIdentity**: `string`
+
+The identity of the node that created the change set.
+
+***
+
+### proof?
+
+> `optional` **proof**: `IProof`
+
+The proof for the change set.

package/docs/reference/interfaces/ISyncChangeSetRequest.md

@@ -4,14 +4,8 @@ Request a trusted node to perform a sync request for a changeset.
 
 ## Properties
 
-### query
+### body
 
-> **query**: `object`
+> **body**: [`ISyncChangeSet`](ISyncChangeSet.md)
 
-The query parameters.
-
-#### changeSetStorageId
-
-> **changeSetStorageId**: `string`
-
-The storage id of the changeset.
+The body of the request.

package/docs/reference/interfaces/ISyncDecryptionKeyRequest.md

@@ -0,0 +1,23 @@
+# Interface: ISyncDecryptionKeyRequest
+
+Request for the decryption key for the synchronised storage.
+
+## Properties
+
+### body
+
+> **body**: `object`
+
+The body of the request.
+
+#### nodeIdentity
+
+> **nodeIdentity**: `string`
+
+The identity of the node making the request.
+
+#### proof
+
+> **proof**: `IProof`
+
+The proof of the request.

package/docs/reference/interfaces/ISyncDecryptionKeyResponse.md

@@ -0,0 +1,17 @@
+# Interface: ISyncDecryptionKeyResponse
+
+Response to a request for the decryption key for the synchronised storage.
+
+## Properties
+
+### body
+
+> **body**: `object`
+
+The body of the response.
+
+#### decryptionKey
+
+> **decryptionKey**: `string`
+
+The decryption key for the synchronised storage as base64.

package/docs/reference/interfaces/ISyncItemChange.md

@@ -20,6 +20,14 @@ The operation being performed on the item.
 
 ***
 
+### nodeIdentity
+
+> **nodeIdentity**: `string`
+
+The node performing the operation.
+
+***
+
 ### id
 
 > **id**: `string`

package/docs/reference/interfaces/ISyncItemRemove.md

@@ -12,6 +12,14 @@ The key of the storage being removed.
 
 ***
 
+### nodeIdentity
+
+> **nodeIdentity**: `string`
+
+The node identity of the entity being removed.
+
+***
+
 ### id
 
 > **id**: `string`

package/docs/reference/interfaces/ISyncReset.md

@@ -0,0 +1,19 @@
+# Interface: ISyncReset
+
+Request to reset the local storage.
+
+## Properties
+
+### storageKey
+
+> **storageKey**: `string`
+
+The key of the storage for the entities in the batch.
+
+***
+
+### resetMode
+
+> **resetMode**: [`SyncNodeIdentityMode`](../type-aliases/SyncNodeIdentityMode.md)
+
+Reset mode, this will use the nodeIdentity in the entities to determine which are local/remote.

package/docs/reference/interfaces/ISynchronisedEntity.md

@@ -4,6 +4,14 @@ The base definition for synchronised entries.
 
 ## Properties
 
+### id
+
+> **id**: `string`
+
+The id of the entry.
+
+***
+
 ### dateModified
 
 > **dateModified**: `string`

package/docs/reference/interfaces/ISynchronisedStorageComponent.md

@@ -8,19 +8,48 @@ Class for performing synchronised storage operations.
 
 ## Methods
 
-### syncChangeSet()
+### getDecryptionKey()
 
-> **syncChangeSet**(`changeSetStorageId`): `Promise`\<`void`\>
+> **getDecryptionKey**(`nodeIdentity`, `proof`): `Promise`\<`string`\>
 
-Synchronise a complete set of changes, assumes this is a trusted node.
+Get the decryption key for the synchronised storage.
+This is used to decrypt the data stored in the synchronised storage.
 
 #### Parameters
 
-##### changeSetStorageId
+##### nodeIdentity
 
 `string`
 
-The id of the change set to synchronise in blob storage.
+The identity of the node requesting the decryption key.
+
+##### proof
+
+`IProof`
+
+The proof of the request so we know the request is from the specified node.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The decryption key.
+
+***
+
+### syncChangeSet()
+
+> **syncChangeSet**(`syncChangeSet`): `Promise`\<`void`\>
+
+Synchronise a set of changes from an untrusted node, assumes this is a trusted node.
+
+#### Parameters
+
+##### syncChangeSet
+
+[`ISyncChangeSet`](ISyncChangeSet.md)
+
+The change set to synchronise.
 
 #### Returns
 

package/docs/reference/type-aliases/SyncNodeIdentityMode.md

@@ -0,0 +1,5 @@
+# Type Alias: SyncNodeIdentityMode
+
+> **SyncNodeIdentityMode** = *typeof* [`SyncNodeIdentityMode`](../variables/SyncNodeIdentityMode.md)\[keyof *typeof* [`SyncNodeIdentityMode`](../variables/SyncNodeIdentityMode.md)\]
+
+The mode to determine how node identities are matched.

package/docs/reference/variables/SyncNodeIdentityMode.md

@@ -0,0 +1,25 @@
+# Variable: SyncNodeIdentityMode
+
+> `const` **SyncNodeIdentityMode**: `object`
+
+The mode to determine how node identities are matched.
+
+## Type declaration
+
+### Local
+
+> `readonly` **Local**: `"local"` = `"local"`
+
+Match the local node identity.
+
+### Remote
+
+> `readonly` **Remote**: `"remote"` = `"remote"`
+
+Match all but the local node identity.
+
+### All
+
+> `readonly` **All**: `"all"` = `"all"`
+
+All match both local and remote entities.

package/docs/reference/variables/SynchronisedStorageTopics.md

@@ -30,6 +30,12 @@ A request has been made for a local item.
 
 A response to a local item request.
 
+### Reset
+
+> `readonly` **Reset**: `"synchronised-storage:reset"` = `"synchronised-storage:reset"`
+
+Reset the storage.
+
 ### BatchRequest
 
 > `readonly` **BatchRequest**: `"synchronised-storage:batch-request"` = `"synchronised-storage:batch-request"`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/synchronised-storage-models",
-	"version": "0.0.1-next.3",
+	"version": "0.0.1-next.5",
 	"description": "Models which define the structure of the synchronised storage connectors and services",
 	"repository": {
 		"type": "git",
@@ -16,7 +16,8 @@
 	"dependencies": {
 		"@twin.org/core": "next",
 		"@twin.org/entity": "next",
-		"@twin.org/nameof": "next"
+		"@twin.org/nameof": "next",
+		"@twin.org/standards-w3c-did": "next"
 	},
 	"main": "./dist/cjs/index.cjs",
 	"module": "./dist/esm/index.mjs",