@twin.org/node-core 0.0.2-next.25 → 0.0.2-next.27

package/docs/reference/functions/{bootstrapNodeUser.md → bootstrapNodeAdminUser.md}

@@ -1,6 +1,6 @@
-# Function: bootstrapNodeUser()
+# Function: bootstrapNodeAdminUser()
 
-> **bootstrapNodeUser**(`engineCore`, `context`, `envVars`, `features`): `Promise`\<`void`\>
+> **bootstrapNodeAdminUser**(`engineCore`, `context`, `envVars`, `features`): `Promise`\<`void`\>
 
 Bootstrap the user.
 
@@ -14,7 +14,7 @@ The engine core for the node.
 
 ### context
 
-`IEngineCoreContext`\<`IEngineServerConfig`, `IEngineState`\>
+`IEngineCoreContext`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>
 
 The context for the node.
 

package/docs/reference/functions/{bootstrapNodeIdentity.md → bootstrapNodeId.md}

@@ -1,6 +1,6 @@
-# Function: bootstrapNodeIdentity()
+# Function: bootstrapNodeId()
 
-> **bootstrapNodeIdentity**(`engineCore`, `context`, `envVars`, `features`): `Promise`\<`void`\>
+> **bootstrapNodeId**(`engineCore`, `context`, `envVars`, `features`): `Promise`\<`void`\>
 
 Bootstrap the node creating any necessary resources.
 
@@ -14,7 +14,7 @@ The engine core for the node.
 
 ### context
 
-`IEngineCoreContext`\<`IEngineServerConfig`, `IEngineState`\>
+`IEngineCoreContext`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>
 
 The context for the node.
 

package/docs/reference/functions/bootstrapSynchronisedStorage.md

@@ -14,7 +14,7 @@ The engine core for the node.
 
 ### context
 
-`IEngineCoreContext`\<`IEngineServerConfig`, `IEngineState`\>
+`IEngineCoreContext`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>
 
 The context for the node.
 

package/docs/reference/functions/bootstrapTenantId.md

@@ -0,0 +1,35 @@
+# Function: bootstrapTenantId()
+
+> **bootstrapTenantId**(`engineCore`, `context`, `envVars`, `features`): `Promise`\<`void`\>
+
+Bootstrap the node creating any necessary resources.
+
+## Parameters
+
+### engineCore
+
+`IEngineCore`
+
+The engine core for the node.
+
+### context
+
+`IEngineCoreContext`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>
+
+The context for the node.
+
+### envVars
+
+[`INodeEnvironmentVariables`](../interfaces/INodeEnvironmentVariables.md)
+
+The environment variables for the node.
+
+### features
+
+[`NodeFeatures`](../type-aliases/NodeFeatures.md)[]
+
+The features that are enabled on the node. The features that are enabled on the node.
+
+## Returns
+
+`Promise`\<`void`\>

package/docs/reference/functions/buildConfiguration.md

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

package/docs/reference/functions/buildEngineConfiguration.md

@@ -1,6 +1,6 @@
 # Function: buildEngineConfiguration()
 
-> **buildEngineConfiguration**(`envVars`): `Promise`\<`IEngineConfig`\>
+> **buildEngineConfiguration**(`envVars`, `contextIdKeys`): `Promise`\<`IEngineConfig`\>
 
 Build the engine core configuration from environment variables.
 
@@ -12,6 +12,12 @@ Build the engine core configuration from environment variables.
 
 The environment variables.
 
+### contextIdKeys
+
+`string`[]
+
+The context ID keys.
+
 ## Returns
 
 `Promise`\<`IEngineConfig`\>

package/docs/reference/functions/buildEngineServerConfiguration.md

@@ -1,6 +1,6 @@
 # Function: buildEngineServerConfiguration()
 
-> **buildEngineServerConfiguration**(`envVars`, `coreEngineConfig`, `serverInfo`, `openApiSpecPath?`, `favIconPath?`): `Promise`\<`IEngineServerConfig`\>
+> **buildEngineServerConfiguration**(`envVars`, `contextIdKeys`, `coreEngineConfig`, `serverInfo`, `openApiSpecPath?`, `favIconPath?`): `Promise`\<`IEngineServerConfig`\>
 
 Handles the configuration of the server.
 
@@ -12,6 +12,12 @@ Handles the configuration of the server.
 
 The environment variables for the engine server.
 
+### contextIdKeys
+
+`string`[]
+
+The context ID keys.
+
 ### coreEngineConfig
 
 `IEngineCoreConfig`

package/docs/reference/functions/createModuleImportUrl.md

@@ -0,0 +1,21 @@
+# Function: createModuleImportUrl()
+
+> **createModuleImportUrl**(`filePath`): `string`
+
+Convert a file path to an import-compatible URL for cross-platform module loading.
+On Windows, adds the 'file://' protocol prefix required for dynamic imports.
+On other platforms, returns the path unchanged.
+
+## Parameters
+
+### filePath
+
+`string`
+
+The absolute file path to convert.
+
+## Returns
+
+`string`
+
+A URL string compatible with dynamic import().

package/docs/reference/functions/getExtensionsCacheDir.md

@@ -0,0 +1,31 @@
+# Function: getExtensionsCacheDir()
+
+> **getExtensionsCacheDir**(`executionDirectory`, `protocol`, `cacheDirectory?`): `string`
+
+Get the extensions cache directory.
+
+## Parameters
+
+### executionDirectory
+
+`string`
+
+The execution directory.
+
+### protocol
+
+[`ModuleProtocol`](../type-aliases/ModuleProtocol.md)
+
+The protocol type for subdirectory organization.
+
+### cacheDirectory?
+
+`string`
+
+The cache directory base path.
+
+## Returns
+
+`string`
+
+The cache directory path.

package/docs/reference/functions/handleHttpsProtocol.md

@@ -0,0 +1,49 @@
+# Function: handleHttpsProtocol()
+
+> **handleHttpsProtocol**(`url`, `executionDirectory`, `maxSizeMb`, `cacheDirectory?`, `ttlHours?`, `forceRefresh?`): `Promise`\<[`IProtocolHandlerResult`](../interfaces/IProtocolHandlerResult.md)\>
+
+Handle the https: protocol by downloading the module if needed.
+
+## Parameters
+
+### url
+
+`string`
+
+The HTTPS URL to download from.
+
+### executionDirectory
+
+`string`
+
+The execution directory.
+
+### maxSizeMb
+
+`number`
+
+The maximum size in MB for the download.
+
+### cacheDirectory?
+
+`string`
+
+The cache directory base path.
+
+### ttlHours?
+
+`number`
+
+TTL in hours for cache expiration.
+
+### forceRefresh?
+
+`boolean`
+
+Whether to force refresh the cache.
+
+## Returns
+
+`Promise`\<[`IProtocolHandlerResult`](../interfaces/IProtocolHandlerResult.md)\>
+
+The resolved path to the downloaded module.

package/docs/reference/functions/handleNpmProtocol.md

@@ -0,0 +1,31 @@
+# Function: handleNpmProtocol()
+
+> **handleNpmProtocol**(`packageName`, `executionDirectory`, `cacheDirectory?`): `Promise`\<[`IProtocolHandlerResult`](../interfaces/IProtocolHandlerResult.md)\>
+
+Handle the npm: protocol by installing the package if needed.
+
+## Parameters
+
+### packageName
+
+`string`
+
+The npm package name (without npm: prefix).
+
+### executionDirectory
+
+`string`
+
+The execution directory.
+
+### cacheDirectory?
+
+`string`
+
+The cache directory base path.
+
+## Returns
+
+`Promise`\<[`IProtocolHandlerResult`](../interfaces/IProtocolHandlerResult.md)\>
+
+The resolved path to the installed module.

package/docs/reference/functions/hashUrl.md

@@ -0,0 +1,19 @@
+# Function: hashUrl()
+
+> **hashUrl**(`url`): `string`
+
+Hash a URL to create a safe filename.
+
+## Parameters
+
+### url
+
+`string`
+
+The URL to hash.
+
+## Returns
+
+`string`
+
+A hashed filename safe for the filesystem.

package/docs/reference/functions/isCacheExpired.md

@@ -0,0 +1,31 @@
+# Function: isCacheExpired()
+
+> **isCacheExpired**(`metadataPath`, `ttlHours`, `forceRefresh`): `Promise`\<`boolean`\>
+
+Check if a cached file has expired based on TTL and force refresh settings.
+
+## Parameters
+
+### metadataPath
+
+`string`
+
+Path to the cache metadata file.
+
+### ttlHours
+
+`number`
+
+Time to live in hours.
+
+### forceRefresh
+
+`boolean`
+
+Whether to force refresh regardless of TTL.
+
+## Returns
+
+`Promise`\<`boolean`\>
+
+True if the cache is expired or should be refreshed.

package/docs/reference/functions/overrideModuleImport.md

@@ -1,8 +1,8 @@
 # Function: overrideModuleImport()
 
-> **overrideModuleImport**(`executionDirectory`): `void`
+> **overrideModuleImport**(`executionDirectory`, `envVars?`): `void`
 
-Override module imports to use local files where possible.
+Override module imports to support protocol-based loading (npm:, https:) and local files.
 
 ## Parameters
 
@@ -12,6 +12,12 @@ Override module imports to use local files where possible.
 
 The execution directory for resolving local module paths.
 
+### envVars?
+
+[`INodeEnvironmentVariables`](../interfaces/INodeEnvironmentVariables.md)
+
+The environment variables containing extension configuration (optional, uses defaults if not provided).
+
 ## Returns
 
 `void`

package/docs/reference/functions/parseModuleProtocol.md

@@ -0,0 +1,19 @@
+# Function: parseModuleProtocol()
+
+> **parseModuleProtocol**(`moduleName`): [`IModuleProtocol`](../interfaces/IModuleProtocol.md)
+
+Parse the protocol from a module name.
+
+## Parameters
+
+### moduleName
+
+`string`
+
+The module name to parse.
+
+## Returns
+
+[`IModuleProtocol`](../interfaces/IModuleProtocol.md)
+
+The parsed protocol information.

package/docs/reference/functions/resolvePackageEntryPoint.md

@@ -0,0 +1,32 @@
+# Function: resolvePackageEntryPoint()
+
+> **resolvePackageEntryPoint**(`packagePath`, `packageName`, `fallback`): `Promise`\<`string`\>
+
+Resolve the main entry point from a package directory using Node.js resolution with fallback.
+Uses require.resolve() when possible for standard Node.js behavior, with manual fallback.
+
+## Parameters
+
+### packagePath
+
+`string`
+
+The absolute path to the package directory.
+
+### packageName
+
+`string`
+
+The package name for require.resolve().
+
+### fallback
+
+`string` = `"index.js"`
+
+The fallback file name if no entry point is found.
+
+## Returns
+
+`Promise`\<`string`\>
+
+The resolved entry point file name (relative to package directory).

package/docs/reference/functions/run.md

@@ -1,6 +1,6 @@
 # Function: run()
 
-> **run**(`nodeOptions?`): `Promise`\<`void`\>
+> **run**(`nodeOptions?`): `Promise`\<`undefined` \| \{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \}\>
 
 Run the TWIN Node server.
 
@@ -14,6 +14,6 @@ Optional configuration options for running the server.
 
 ## Returns
 
-`Promise`\<`void`\>
+`Promise`\<`undefined` \| \{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \}\>
 
-A promise that resolves when the server is started.
+A promise that resolves when the server is started containing a shutdown method.

package/docs/reference/functions/start.md

@@ -1,6 +1,6 @@
 # Function: start()
 
-> **start**(`nodeOptions`, `nodeEngineConfig`, `envVars`): `Promise`\<`undefined` \| \{ `engine`: `Engine`\<`IEngineServerConfig`, `IEngineState`\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \}\>
+> **start**(`nodeOptions`, `nodeEngineConfig`, `envVars`, `contextIdKeys?`): `Promise`\<`undefined` \| \{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \}\>
 
 Start the engine server.
 
@@ -24,8 +24,14 @@ The configuration for the engine server.
 
 The environment variables.
 
+### contextIdKeys?
+
+`string`[]
+
+The context ID keys.
+
 ## Returns
 
-`Promise`\<`undefined` \| \{ `engine`: `Engine`\<`IEngineServerConfig`, `IEngineState`\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \}\>
+`Promise`\<`undefined` \| \{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \}\>
 
 The engine server.

package/docs/reference/index.md

@@ -2,14 +2,19 @@
 
 ## Interfaces
 
+- [ICacheMetadata](interfaces/ICacheMetadata.md)
 - [IEngineEnvironmentVariables](interfaces/IEngineEnvironmentVariables.md)
 - [IEngineServerEnvironmentVariables](interfaces/IEngineServerEnvironmentVariables.md)
+- [IModuleProtocol](interfaces/IModuleProtocol.md)
 - [INodeEngineConfig](interfaces/INodeEngineConfig.md)
+- [INodeEngineState](interfaces/INodeEngineState.md)
 - [INodeEnvironmentVariables](interfaces/INodeEnvironmentVariables.md)
 - [INodeOptions](interfaces/INodeOptions.md)
+- [IProtocolHandlerResult](interfaces/IProtocolHandlerResult.md)
 
 ## Type Aliases
 
+- [ModuleProtocol](type-aliases/ModuleProtocol.md)
 - [NodeExtensionInitialiseMethod](type-aliases/NodeExtensionInitialiseMethod.md)
 - [NodeExtensionInitialiseEngineMethod](type-aliases/NodeExtensionInitialiseEngineMethod.md)
 - [NodeExtensionInitialiseEngineServerMethod](type-aliases/NodeExtensionInitialiseEngineServerMethod.md)
@@ -24,13 +29,16 @@
 - [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)
+- [ModuleProtocol](variables/ModuleProtocol.md)
 - [NodeFeatures](variables/NodeFeatures.md)
 
 ## Functions
 
 - [bootstrap](functions/bootstrap.md)
-- [bootstrapNodeIdentity](functions/bootstrapNodeIdentity.md)
-- [bootstrapNodeUser](functions/bootstrapNodeUser.md)
+- [bootstrapContextIdHandlers](functions/bootstrapContextIdHandlers.md)
+- [bootstrapNodeId](functions/bootstrapNodeId.md)
+- [bootstrapTenantId](functions/bootstrapTenantId.md)
+- [bootstrapNodeAdminUser](functions/bootstrapNodeAdminUser.md)
 - [bootstrapImmutableProofMethod](functions/bootstrapImmutableProofMethod.md)
 - [bootstrapBlobEncryption](functions/bootstrapBlobEncryption.md)
 - [bootstrapAuth](functions/bootstrapAuth.md)
@@ -54,3 +62,11 @@
 - [loadTextFile](functions/loadTextFile.md)
 - [loadJsonFile](functions/loadJsonFile.md)
 - [getFeatures](functions/getFeatures.md)
+- [parseModuleProtocol](functions/parseModuleProtocol.md)
+- [hashUrl](functions/hashUrl.md)
+- [getExtensionsCacheDir](functions/getExtensionsCacheDir.md)
+- [handleNpmProtocol](functions/handleNpmProtocol.md)
+- [isCacheExpired](functions/isCacheExpired.md)
+- [handleHttpsProtocol](functions/handleHttpsProtocol.md)
+- [resolvePackageEntryPoint](functions/resolvePackageEntryPoint.md)
+- [createModuleImportUrl](functions/createModuleImportUrl.md)

package/docs/reference/interfaces/ICacheMetadata.md

@@ -0,0 +1,27 @@
+# Interface: ICacheMetadata
+
+Metadata for cached HTTPS extensions.
+
+## Properties
+
+### downloadedAt
+
+> **downloadedAt**: `number`
+
+Timestamp when the file was downloaded.
+
+***
+
+### url
+
+> **url**: `string`
+
+Original URL of the cached file.
+
+***
+
+### size
+
+> **size**: `number`
+
+Size of the cached file in bytes.

package/docs/reference/interfaces/IEngineEnvironmentVariables.md

@@ -32,6 +32,30 @@ The name of the state file.
 
 ***
 
+### tenantEnabled?
+
+> `optional` **tenantEnabled**: `string`
+
+Is multi-tenant support enabled, defaults to false.
+
+***
+
+### tenantId?
+
+> `optional` **tenantId**: `string`
+
+A tenant id to use as a default for the node.
+
+***
+
+### tenantApiKey?
+
+> `optional` **tenantApiKey**: `string`
+
+A tenant api key to use as a default for the node.
+
+***
+
 ### entityStorageConnectorType?
 
 > `optional` **entityStorageConnectorType**: `string`
@@ -571,15 +595,6 @@ Are the messaging components enabled, defaults to false.
 
 ***
 
-### messagingTemplates?
-
-> `optional` **messagingTemplates**: `string`
-
-An initial set of templates for the messages.
-Use the @json: prefix to specify the path to the JSON file.
-
-***
-
 ### awsSesRegion?
 
 > `optional` **awsSesRegion**: `string`

package/docs/reference/interfaces/IEngineServerEnvironmentVariables.md

@@ -48,6 +48,42 @@ The name of the state file.
 
 ***
 
+### tenantEnabled?
+
+> `optional` **tenantEnabled**: `string`
+
+Is multi-tenant support enabled, defaults to false.
+
+#### Inherited from
+
+[`IEngineEnvironmentVariables`](IEngineEnvironmentVariables.md).[`tenantEnabled`](IEngineEnvironmentVariables.md#tenantenabled)
+
+***
+
+### tenantId?
+
+> `optional` **tenantId**: `string`
+
+A tenant id to use as a default for the node.
+
+#### Inherited from
+
+[`IEngineEnvironmentVariables`](IEngineEnvironmentVariables.md).[`tenantId`](IEngineEnvironmentVariables.md#tenantid)
+
+***
+
+### tenantApiKey?
+
+> `optional` **tenantApiKey**: `string`
+
+A tenant api key to use as a default for the node.
+
+#### Inherited from
+
+[`IEngineEnvironmentVariables`](IEngineEnvironmentVariables.md).[`tenantApiKey`](IEngineEnvironmentVariables.md#tenantapikey)
+
+***
+
 ### entityStorageConnectorType?
 
 > `optional` **entityStorageConnectorType**: `string`
@@ -855,19 +891,6 @@ Are the messaging components enabled, defaults to false.
 
 ***
 
-### messagingTemplates?
-
-> `optional` **messagingTemplates**: `string`
-
-An initial set of templates for the messages.
-Use the @json: prefix to specify the path to the JSON file.
-
-#### Inherited from
-
-[`IEngineEnvironmentVariables`](IEngineEnvironmentVariables.md).[`messagingTemplates`](IEngineEnvironmentVariables.md#messagingtemplates)
-
-***
-
 ### awsSesRegion?
 
 > `optional` **awsSesRegion**: `string`

package/docs/reference/interfaces/IModuleProtocol.md

@@ -0,0 +1,27 @@
+# Interface: IModuleProtocol
+
+The parsed module protocol information.
+
+## Properties
+
+### protocol
+
+> **protocol**: [`ModuleProtocol`](../type-aliases/ModuleProtocol.md)
+
+The protocol type.
+
+***
+
+### identifier
+
+> **identifier**: `string`
+
+The identifier after the protocol (or the original if no protocol).
+
+***
+
+### original
+
+> **original**: `string`
+
+The original module string.