@twin.org/node-core 0.0.2-next.9 → 0.0.3-next.1

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/directoryExists.md

@@ -0,0 +1,19 @@
+# Function: directoryExists()
+
+> **directoryExists**(`directory`): `Promise`\<`boolean`\>
+
+Does the specified directory exist.
+
+## Parameters
+
+### directory
+
+`string`
+
+The directory to check for existence.
+
+## Returns
+
+`Promise`\<`boolean`\>
+
+True if the directory exists.

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/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/getFiles.md

@@ -0,0 +1,19 @@
+# Function: getFiles()
+
+> **getFiles**(`directory`): `Promise`\<`string`[]\>
+
+Get the files in the directory.
+
+## Parameters
+
+### directory
+
+`string`
+
+The directory to get the files from.
+
+## Returns
+
+`Promise`\<`string`[]\>
+
+The list of files in the directory.

package/docs/reference/functions/getSubFolders.md

@@ -0,0 +1,19 @@
+# Function: getSubFolders()
+
+> **getSubFolders**(`directory`): `Promise`\<`string`[]\>
+
+Get the sub folders for the folder.
+
+## Parameters
+
+### directory
+
+`string`
+
+The directory to get the sub folders.
+
+## Returns
+
+`Promise`\<`string`[]\>
+
+The list of sub folders.

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`\<\{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \} \| `undefined`\>
 
 Run the TWIN Node server.
 
@@ -14,6 +14,6 @@ Optional configuration options for running the server.
 
 ## Returns
 
-`Promise`\<`void`\>
+`Promise`\<\{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \} \| `undefined`\>
 
-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/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`, `contextIdKeys?`): `Promise`\<\{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \} \| `undefined`\>
 
 Start the engine server.
 
@@ -10,11 +10,11 @@ Start the engine server.
 
 Optional run options for the engine server.
 
-`undefined` | [`INodeOptions`](../interfaces/INodeOptions.md)
+[`INodeOptions`](../interfaces/INodeOptions.md) | `undefined`
 
-### engineServerConfig
+### nodeEngineConfig
 
-`IEngineServerConfig`
+[`INodeEngineConfig`](../interfaces/INodeEngineConfig.md)
 
 The configuration for 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`; \}\>
+`Promise`\<\{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>; `server`: `EngineServer`; `shutdown`: () => `Promise`\<`void`\>; \} \| `undefined`\>
 
 The engine server.

package/docs/reference/index.md

@@ -2,30 +2,53 @@
 
 ## 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)
+- [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)
+- [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)
 - [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)
@@ -33,6 +56,17 @@
 - [initialiseLocales](functions/initialiseLocales.md)
 - [getExecutionDirectory](functions/getExecutionDirectory.md)
 - [fileExists](functions/fileExists.md)
+- [directoryExists](functions/directoryExists.md)
+- [getSubFolders](functions/getSubFolders.md)
+- [getFiles](functions/getFiles.md)
 - [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.