@twin.org/node-core 0.0.2-next.16 → 0.0.2-next.18

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

@@ -27,6 +27,10 @@ export interface IEngineEnvironmentVariables {
      * A prefix for all the table in entity-storage, can be empty.
      */
     entityStorageTablePrefix?: string;
+    /**
+     * AWS DynamoDB auth mode, either credentials or pod.
+     */
+    awsDynamodbAuthMode?: string;
     /**
      * AWS Dynamo DB access key id.
      */
@@ -194,25 +198,29 @@ export interface IEngineEnvironmentVariables {
      */
     blobStoragePrefix?: string;
     /**
-     * AWS S3 access key id.
+     * AWS S3 region.
      */
-    awsS3AccessKeyId?: string;
+    awsS3Region?: string;
     /**
      * AWS S3 bucket name.
      */
     awsS3BucketName?: string;
     /**
-     * AWS S3 endpoint.
+     * AWS S3 auth mode, either credentials or pod, defaults to credentials.
      */
-    awsS3Endpoint?: string;
+    awsS3AuthMode?: string;
     /**
-     * AWS S3 region.
+     * AWS S3 access key id.
      */
-    awsS3Region?: string;
+    awsS3AccessKeyId?: string;
     /**
      * AWS S3 secret access key.
      */
     awsS3SecretAccessKey?: string;
+    /**
+     * AWS S3 endpoint.
+     */
+    awsS3Endpoint?: string;
     /**
      * Azure Storage account key.
      */
@@ -282,6 +290,14 @@ export interface IEngineEnvironmentVariables {
      * Use the @json: prefix to specify the path to the JSON file.
      */
     messagingTemplates?: string;
+    /**
+     * AWS SES region.
+     */
+    awsSesRegion?: string;
+    /**
+     * AWS SES auth mode, either credentials or pod, defaults to credentials.
+     */
+    awsSesAuthMode?: string;
     /**
      * AWS SES secret access key.
      */
@@ -290,10 +306,6 @@ export interface IEngineEnvironmentVariables {
      * AWS SES access key id.
      */
     awsSesAccessKeyId?: string;
-    /**
-     * AWS SES region.
-     */
-    awsSesRegion?: string;
     /**
      * AWS SES endpoint.
      */
@@ -424,7 +436,7 @@ export interface IEngineEnvironmentVariables {
     synchronisedStorageTrustedUrl?: string;
     /**
      * The key for the smart contract which contains the verifiable storage pointer store for synchronised storage.
-     * This only required if using a custom verifiable storage item, otherwise it will default the the network name.
+     * This only required if using a custom verifiable storage item, otherwise it will default to the network name.
      */
     synchronisedStorageVerifiableStorageKeyId?: string;
     /**
@@ -522,10 +534,15 @@ export interface IEngineEnvironmentVariables {
      */
     dataSpaceConnectorEnabled?: string;
     /**
-     * The application configuration for the data space connector.
-     * Use the @json: prefix to specify the path to the JSON configuration file.
+     * The length of time to retain the activity logs for in minutes, set to -1 to keep forever.
+     * @default 10
+     */
+    dataSpaceConnectorRetainActivityLogsFor?: string;
+    /**
+     * The interval for cleaning up the activity logs.
+     * @default 60
      */
-    dataSpaceConnectorApps?: string;
+    dataSpaceConnectorActivityLogsCleanUpInterval?: string;
     /**
      * Enable verifiable credential authentication for the API.
      */
@@ -535,4 +552,8 @@ export interface IEngineEnvironmentVariables {
      * Defaults to node-authentication-assertion.
      */
     vcAuthenticationVerificationMethodId?: string;
+    /**
+     * A comma separated list of additional node extensions to load, the initialiseExtension method will be called for each extension.
+     */
+    extensions?: string;
 }

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

@@ -0,0 +1,6 @@
+import type { IEngineServerConfig } from "@twin.org/engine-server-types";
+/**
+ * The config for the node.
+ */
+export interface INodeEngineConfig extends IEngineServerConfig {
+}

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

@@ -1,5 +1,6 @@
 import type { IEngineCore, IEngineServer, IEngineStateStorage } from "@twin.org/engine-models";
 import type { IEngineConfig } from "@twin.org/engine-types";
+import type { INodeEngineConfig } from "./INodeEngineConfig";
 import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables";
 /**
  * The options when running the node.
@@ -56,7 +57,7 @@ export interface INodeOptions {
     /**
      * Method to extend the engine configuration with any additional custom configuration.
      */
-    extendConfig?: (config: IEngineConfig) => Promise<void>;
+    extendConfig?: (envVars: INodeEnvironmentVariables, config: INodeEngineConfig) => Promise<void>;
     /**
      * Method to extend the engine with any additional options.
      */

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

@@ -0,0 +1,27 @@
+import type { IEngineCore, IEngineServer } from "@twin.org/engine-models";
+import type { INodeEngineConfig } from "./INodeEngineConfig";
+import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables";
+/**
+ * The type for the initialise method of an extension module.
+ * @param envVars The environment variables for the node.
+ * @param nodeEngineConfig The node engine config.
+ */
+export type NodeExtensionInitialiseMethod = (envVars: INodeEnvironmentVariables, nodeEngineConfig: INodeEngineConfig) => Promise<void>;
+/**
+ * The type for the initialise engine method of an extension module.
+ * This is called when the engine has been constructed but not yet started.
+ * @param engineCore The engine core instance.
+ */
+export type NodeExtensionInitialiseEngineMethod = (engineCore: IEngineCore) => Promise<void>;
+/**
+ * The type for the initialise engine server method of an extension module.
+ * This is called when the engine server has been constructed but not yet started.
+ * @param engineCore The engine core instance.
+ * @param engineServer The engine server instance.
+ */
+export type NodeExtensionInitialiseEngineServerMethod = (engineCore: IEngineCore, engineServer: IEngineServer) => Promise<void>;
+/**
+ * The type for the shutdown method of an extension module.
+ * This is called when the engine is shutting down.
+ */
+export type NodeExtensionShutdownMethod = () => Promise<void>;

package/dist/types/node.d.ts

@@ -1,5 +1,5 @@
 import type { IServerInfo } from "@twin.org/api-models";
-import type { IEngineServerConfig } from "@twin.org/engine-server-types";
+import type { INodeEngineConfig } from "./models/INodeEngineConfig";
 import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables";
 import type { INodeOptions } from "./models/INodeOptions";
 /**
@@ -22,7 +22,7 @@ export declare function buildConfiguration(processEnv: {
     nodeEnvVars: INodeEnvironmentVariables & {
         [id: string]: string | unknown;
     };
-    engineServerConfig: IEngineServerConfig;
+    nodeEngineConfig: INodeEngineConfig;
 }>;
 /**
  * Override module imports to use local files where possible.

package/dist/types/server.d.ts

@@ -2,16 +2,18 @@ import { Engine } from "@twin.org/engine";
 import { type IEngineState } from "@twin.org/engine-models";
 import { EngineServer } from "@twin.org/engine-server";
 import type { IEngineServerConfig } from "@twin.org/engine-server-types";
+import type { INodeEngineConfig } from "./models/INodeEngineConfig";
 import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables";
 import type { INodeOptions } from "./models/INodeOptions";
 /**
  * Start the engine server.
  * @param nodeOptions Optional run options for the engine server.
- * @param engineServerConfig The configuration for the engine server.
+ * @param nodeEngineConfig The configuration for the engine server.
  * @param envVars The environment variables.
  * @returns The engine server.
  */
-export declare function start(nodeOptions: INodeOptions | undefined, engineServerConfig: IEngineServerConfig, envVars: INodeEnvironmentVariables): Promise<{
+export declare function start(nodeOptions: INodeOptions | undefined, nodeEngineConfig: INodeEngineConfig, envVars: INodeEnvironmentVariables): Promise<{
     engine: Engine<IEngineServerConfig, IEngineState>;
     server: EngineServer;
+    shutdown: () => Promise<void>;
 } | undefined>;

package/docs/changelog.md

@@ -1,5 +1,20 @@
 # @twin.org/node-core - Changelog
 
+## [0.0.2-next.18](https://github.com/twinfoundation/node/compare/node-core-v0.0.2-next.17...node-core-v0.0.2-next.18) (2025-10-03)
+
+
+### Features
+
+* improve error handling for extensions and logging ([bd84fde](https://github.com/twinfoundation/node/commit/bd84fde67e5a9db6ac66730397992401ca52e88c))
+
+## [0.0.2-next.17](https://github.com/twinfoundation/node/compare/node-core-v0.0.2-next.16...node-core-v0.0.2-next.17) (2025-10-02)
+
+
+### Features
+
+* add extensions support ([476d5a8](https://github.com/twinfoundation/node/commit/476d5a864026a2f78e5b02bc9eb81359777a4a45))
+* updating linting ([feacd17](https://github.com/twinfoundation/node/commit/feacd178bb025bcd29a0ae6e4b8e79f23a989169))
+
 ## [0.0.2-next.16](https://github.com/twinfoundation/node/compare/node-core-v0.0.2-next.15...node-core-v0.0.2-next.16) (2025-09-29)
 
 

package/docs/reference/functions/buildConfiguration.md

@@ -1,6 +1,6 @@
 # Function: buildConfiguration()
 
-> **buildConfiguration**(`processEnv`, `options`, `serverInfo`): `Promise`\<\{ `nodeEnvVars`: [`INodeEnvironmentVariables`](../interfaces/INodeEnvironmentVariables.md) & `object`; `engineServerConfig`: `IEngineServerConfig`; \}\>
+> **buildConfiguration**(`processEnv`, `options`, `serverInfo`): `Promise`\<\{ `nodeEnvVars`: [`INodeEnvironmentVariables`](../interfaces/INodeEnvironmentVariables.md) & `object`; `nodeEngineConfig`: [`INodeEngineConfig`](../interfaces/INodeEngineConfig.md); \}\>
 
 Build the configuration for the TWIN Node server.
 
@@ -24,7 +24,7 @@ The server information.
 
 ## Returns
 
-`Promise`\<\{ `nodeEnvVars`: [`INodeEnvironmentVariables`](../interfaces/INodeEnvironmentVariables.md) & `object`; `engineServerConfig`: `IEngineServerConfig`; \}\>
+`Promise`\<\{ `nodeEnvVars`: [`INodeEnvironmentVariables`](../interfaces/INodeEnvironmentVariables.md) & `object`; `nodeEngineConfig`: [`INodeEngineConfig`](../interfaces/INodeEngineConfig.md); \}\>
 
 A promise that resolves to the engine server configuration, environment prefix, environment variables,
 and options.

package/docs/reference/functions/buildEngineServerConfiguration.md

@@ -40,4 +40,4 @@ The path to the favicon.
 
 `Promise`\<`IEngineServerConfig`\>
 
-The the config for the core and the server.
+The config for the core and the server.

package/docs/reference/functions/extensionsConfiguration.md

@@ -0,0 +1,25 @@
+# Function: extensionsConfiguration()
+
+> **extensionsConfiguration**(`envVars`, `nodeEngineConfig`): `Promise`\<[`INodeEngineConfig`](../interfaces/INodeEngineConfig.md)\>
+
+Handles the configuration of the extensions.
+
+## Parameters
+
+### envVars
+
+[`INodeEnvironmentVariables`](../interfaces/INodeEnvironmentVariables.md)
+
+The environment variables for the node.
+
+### nodeEngineConfig
+
+[`INodeEngineConfig`](../interfaces/INodeEngineConfig.md)
+
+The node engine config.
+
+## Returns
+
+`Promise`\<[`INodeEngineConfig`](../interfaces/INodeEngineConfig.md)\>
+
+The config for the core and the server.

package/docs/reference/functions/extensionsInitialiseEngine.md

@@ -0,0 +1,25 @@
+# Function: extensionsInitialiseEngine()
+
+> **extensionsInitialiseEngine**(`envVars`, `engineCore`): `Promise`\<`void`\>
+
+Handles the initialisation of the extensions when the engine has been constructed.
+
+## Parameters
+
+### envVars
+
+[`INodeEnvironmentVariables`](../interfaces/INodeEnvironmentVariables.md)
+
+The environment variables for the node.
+
+### engineCore
+
+`IEngineCore`
+
+The engine core instance.
+
+## Returns
+
+`Promise`\<`void`\>
+
+Nothing.

package/docs/reference/functions/extensionsInitialiseEngineServer.md

@@ -0,0 +1,31 @@
+# Function: extensionsInitialiseEngineServer()
+
+> **extensionsInitialiseEngineServer**(`envVars`, `engineCore`, `engineServer`): `Promise`\<`void`\>
+
+Handles the initialisation of the extensions when the engine server has been constructed.
+
+## Parameters
+
+### envVars
+
+[`INodeEnvironmentVariables`](../interfaces/INodeEnvironmentVariables.md)
+
+The environment variables for the node.
+
+### engineCore
+
+`IEngineCore`
+
+The engine core instance.
+
+### engineServer
+
+`IEngineServer`
+
+The engine server instance.
+
+## Returns
+
+`Promise`\<`void`\>
+
+Nothing.

package/docs/reference/functions/shutdownExtensions.md

@@ -0,0 +1,25 @@
+# Function: shutdownExtensions()
+
+> **shutdownExtensions**(`envVars`, `engineCore`): `Promise`\<`void`\>
+
+Handles the shutdown of the extensions.
+
+## Parameters
+
+### envVars
+
+[`INodeEnvironmentVariables`](../interfaces/INodeEnvironmentVariables.md)
+
+The environment variables for the node.
+
+### engineCore
+
+`IEngineCore`
+
+The engine core instance.
+
+## Returns
+
+`Promise`\<`void`\>
+
+Nothing.

package/docs/reference/functions/start.md

@@ -1,6 +1,6 @@
 # Function: start()
 
-> **start**(`nodeOptions`, `engineServerConfig`, `envVars`): `Promise`\<`undefined` \| \{ `engine`: `Engine`\<`IEngineServerConfig`, `IEngineState`\>; `server`: `EngineServer`; \}\>
+> **start**(`nodeOptions`, `nodeEngineConfig`, `envVars`): `Promise`\<`undefined` \| \{ `engine`: `Engine`\<`IEngineServerConfig`, `IEngineState`\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \}\>
 
 Start the engine server.
 
@@ -12,9 +12,9 @@ Optional run options for the engine server.
 
 `undefined` | [`INodeOptions`](../interfaces/INodeOptions.md)
 
-### engineServerConfig
+### nodeEngineConfig
 
-`IEngineServerConfig`
+[`INodeEngineConfig`](../interfaces/INodeEngineConfig.md)
 
 The configuration for the engine server.
 
@@ -26,6 +26,6 @@ The environment variables.
 
 ## Returns
 
-`Promise`\<`undefined` \| \{ `engine`: `Engine`\<`IEngineServerConfig`, `IEngineState`\>; `server`: `EngineServer`; \}\>
+`Promise`\<`undefined` \| \{ `engine`: `Engine`\<`IEngineServerConfig`, `IEngineState`\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \}\>
 
 The engine server.

package/docs/reference/index.md

@@ -4,15 +4,26 @@
 
 - [IEngineEnvironmentVariables](interfaces/IEngineEnvironmentVariables.md)
 - [IEngineServerEnvironmentVariables](interfaces/IEngineServerEnvironmentVariables.md)
+- [INodeEngineConfig](interfaces/INodeEngineConfig.md)
 - [INodeEnvironmentVariables](interfaces/INodeEnvironmentVariables.md)
 - [INodeOptions](interfaces/INodeOptions.md)
 
 ## Type Aliases
 
+- [NodeExtensionInitialiseMethod](type-aliases/NodeExtensionInitialiseMethod.md)
+- [NodeExtensionInitialiseEngineMethod](type-aliases/NodeExtensionInitialiseEngineMethod.md)
+- [NodeExtensionInitialiseEngineServerMethod](type-aliases/NodeExtensionInitialiseEngineServerMethod.md)
+- [NodeExtensionShutdownMethod](type-aliases/NodeExtensionShutdownMethod.md)
 - [NodeFeatures](type-aliases/NodeFeatures.md)
 
 ## Variables
 
+- [ATTESTATION\_VERIFICATION\_METHOD\_ID](variables/ATTESTATION_VERIFICATION_METHOD_ID.md)
+- [IMMUTABLE\_PROOF\_VERIFICATION\_METHOD\_ID](variables/IMMUTABLE_PROOF_VERIFICATION_METHOD_ID.md)
+- [BLOB\_STORAGE\_ENCRYPTION\_KEY\_ID](variables/BLOB_STORAGE_ENCRYPTION_KEY_ID.md)
+- [SYNCHRONISED\_STORAGE\_BLOB\_STORAGE\_ENCRYPTION\_KEY\_ID](variables/SYNCHRONISED_STORAGE_BLOB_STORAGE_ENCRYPTION_KEY_ID.md)
+- [VC\_AUTHENTICATION\_VERIFICATION\_METHOD\_ID](variables/VC_AUTHENTICATION_VERIFICATION_METHOD_ID.md)
+- [AUTH\_SIGNING\_KEY\_ID](variables/AUTH_SIGNING_KEY_ID.md)
 - [NodeFeatures](variables/NodeFeatures.md)
 
 ## Functions
@@ -26,6 +37,10 @@
 - [bootstrapSynchronisedStorage](functions/bootstrapSynchronisedStorage.md)
 - [buildEngineConfiguration](functions/buildEngineConfiguration.md)
 - [buildEngineServerConfiguration](functions/buildEngineServerConfiguration.md)
+- [extensionsConfiguration](functions/extensionsConfiguration.md)
+- [extensionsInitialiseEngine](functions/extensionsInitialiseEngine.md)
+- [extensionsInitialiseEngineServer](functions/extensionsInitialiseEngineServer.md)
+- [shutdownExtensions](functions/shutdownExtensions.md)
 - [run](functions/run.md)
 - [buildConfiguration](functions/buildConfiguration.md)
 - [overrideModuleImport](functions/overrideModuleImport.md)

package/docs/reference/interfaces/IEngineEnvironmentVariables.md

@@ -57,6 +57,14 @@ A prefix for all the table in entity-storage, can be empty.
 
 ***
 
+### awsDynamodbAuthMode?
+
+> `optional` **awsDynamodbAuthMode**: `string`
+
+AWS DynamoDB auth mode, either credentials or pod.
+
+***
+
 ### awsDynamodbAccessKeyId?
 
 > `optional` **awsDynamodbAccessKeyId**: `string`
@@ -387,11 +395,11 @@ A prefix for all the blobs in blob-storage, can be empty.
 
 ***
 
-### awsS3AccessKeyId?
+### awsS3Region?
 
-> `optional` **awsS3AccessKeyId**: `string`
+> `optional` **awsS3Region**: `string`
 
-AWS S3 access key id.
+AWS S3 region.
 
 ***
 
@@ -403,19 +411,19 @@ AWS S3 bucket name.
 
 ***
 
-### awsS3Endpoint?
+### awsS3AuthMode?
 
-> `optional` **awsS3Endpoint**: `string`
+> `optional` **awsS3AuthMode**: `string`
 
-AWS S3 endpoint.
+AWS S3 auth mode, either credentials or pod, defaults to credentials.
 
 ***
 
-### awsS3Region?
+### awsS3AccessKeyId?
 
-> `optional` **awsS3Region**: `string`
+> `optional` **awsS3AccessKeyId**: `string`
 
-AWS S3 region.
+AWS S3 access key id.
 
 ***
 
@@ -427,6 +435,14 @@ AWS S3 secret access key.
 
 ***
 
+### awsS3Endpoint?
+
+> `optional` **awsS3Endpoint**: `string`
+
+AWS S3 endpoint.
+
+***
+
 ### azureStorageAccountKey?
 
 > `optional` **azureStorageAccountKey**: `string`
@@ -564,6 +580,22 @@ Use the @json: prefix to specify the path to the JSON file.
 
 ***
 
+### awsSesRegion?
+
+> `optional` **awsSesRegion**: `string`
+
+AWS SES region.
+
+***
+
+### awsSesAuthMode?
+
+> `optional` **awsSesAuthMode**: `string`
+
+AWS SES auth mode, either credentials or pod, defaults to credentials.
+
+***
+
 ### awsSesSecretAccessKey?
 
 > `optional` **awsSesSecretAccessKey**: `string`
@@ -580,14 +612,6 @@ AWS SES access key id.
 
 ***
 
-### awsSesRegion?
-
-> `optional` **awsSesRegion**: `string`
-
-AWS SES region.
-
-***
-
 ### awsSesEndpoint?
 
 > `optional` **awsSesEndpoint**: `string`
@@ -849,7 +873,7 @@ Url which points to the api for a trusted synchronised storage node, not require
 > `optional` **synchronisedStorageVerifiableStorageKeyId**: `string`
 
 The key for the smart contract which contains the verifiable storage pointer store for synchronised storage.
-This only required if using a custom verifiable storage item, otherwise it will default the the network name.
+This only required if using a custom verifiable storage item, otherwise it will default to the network name.
 
 ***
 
@@ -1047,12 +1071,31 @@ Is the data space connector enabled, defaults to false.
 
 ***
 
-### dataSpaceConnectorApps?
+### dataSpaceConnectorRetainActivityLogsFor?
 
-> `optional` **dataSpaceConnectorApps**: `string`
+> `optional` **dataSpaceConnectorRetainActivityLogsFor**: `string`
 
-The application configuration for the data space connector.
-Use the @json: prefix to specify the path to the JSON configuration file.
+The length of time to retain the activity logs for in minutes, set to -1 to keep forever.
+
+#### Default
+
+```ts
+10
+```
+
+***
+
+### dataSpaceConnectorActivityLogsCleanUpInterval?
+
+> `optional` **dataSpaceConnectorActivityLogsCleanUpInterval**: `string`
+
+The interval for cleaning up the activity logs.
+
+#### Default
+
+```ts
+60
+```
 
 ***
 
@@ -1070,3 +1113,11 @@ Enable verifiable credential authentication for the API.
 
 Verifiable credential assertion for node to node communication.
 Defaults to node-authentication-assertion.
+
+***
+
+### extensions?
+
+> `optional` **extensions**: `string`
+
+A comma separated list of additional node extensions to load, the initialiseExtension method will be called for each extension.