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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/README.md +1 -1
  2. package/dist/es/bootstrap.js +374 -0
  3. package/dist/es/bootstrap.js.map +1 -0
  4. package/dist/es/builders/engineEnvBuilder.js +1051 -0
  5. package/dist/es/builders/engineEnvBuilder.js.map +1 -0
  6. package/dist/es/builders/engineServerEnvBuilder.js +197 -0
  7. package/dist/es/builders/engineServerEnvBuilder.js.map +1 -0
  8. package/dist/es/builders/extensionsBuilder.js +100 -0
  9. package/dist/es/builders/extensionsBuilder.js.map +1 -0
  10. package/dist/es/defaults.js +9 -0
  11. package/dist/es/defaults.js.map +1 -0
  12. package/dist/es/identity.js +169 -0
  13. package/dist/es/identity.js.map +1 -0
  14. package/dist/es/index.js +23 -0
  15. package/dist/es/index.js.map +1 -0
  16. package/dist/es/models/ICacheMetadata.js +4 -0
  17. package/dist/es/models/ICacheMetadata.js.map +1 -0
  18. package/dist/es/models/IEngineEnvironmentVariables.js +4 -0
  19. package/dist/es/models/IEngineEnvironmentVariables.js.map +1 -0
  20. package/dist/es/models/IEngineServerEnvironmentVariables.js +2 -0
  21. package/dist/es/models/IEngineServerEnvironmentVariables.js.map +1 -0
  22. package/dist/es/models/IModuleProtocol.js +2 -0
  23. package/dist/es/models/IModuleProtocol.js.map +1 -0
  24. package/dist/es/models/INodeEngineConfig.js +2 -0
  25. package/dist/es/models/INodeEngineConfig.js.map +1 -0
  26. package/dist/es/models/INodeEngineState.js +2 -0
  27. package/dist/es/models/INodeEngineState.js.map +1 -0
  28. package/dist/es/models/INodeEnvironmentVariables.js +2 -0
  29. package/dist/es/models/INodeEnvironmentVariables.js.map +1 -0
  30. package/dist/es/models/INodeOptions.js +2 -0
  31. package/dist/es/models/INodeOptions.js.map +1 -0
  32. package/dist/es/models/IProtocolHandlerResult.js +4 -0
  33. package/dist/es/models/IProtocolHandlerResult.js.map +1 -0
  34. package/dist/es/models/moduleProtocol.js +29 -0
  35. package/dist/es/models/moduleProtocol.js.map +1 -0
  36. package/dist/es/models/nodeExtensionMethods.js +2 -0
  37. package/dist/es/models/nodeExtensionMethods.js.map +1 -0
  38. package/dist/es/models/nodeFeatures.js +21 -0
  39. package/dist/es/models/nodeFeatures.js.map +1 -0
  40. package/dist/es/node.js +265 -0
  41. package/dist/es/node.js.map +1 -0
  42. package/dist/es/server.js +74 -0
  43. package/dist/es/server.js.map +1 -0
  44. package/dist/es/utils.js +418 -0
  45. package/dist/es/utils.js.map +1 -0
  46. package/dist/types/bootstrap.d.ts +27 -10
  47. package/dist/types/builders/engineEnvBuilder.d.ts +3 -2
  48. package/dist/types/builders/engineServerEnvBuilder.d.ts +3 -2
  49. package/dist/types/builders/extensionsBuilder.d.ts +2 -2
  50. package/dist/types/identity.d.ts +14 -0
  51. package/dist/types/index.d.ts +20 -15
  52. package/dist/types/models/ICacheMetadata.d.ts +17 -0
  53. package/dist/types/models/IEngineEnvironmentVariables.d.ts +12 -5
  54. package/dist/types/models/IEngineServerEnvironmentVariables.d.ts +1 -1
  55. package/dist/types/models/IModuleProtocol.d.ts +18 -0
  56. package/dist/types/models/INodeEngineState.d.ts +22 -0
  57. package/dist/types/models/INodeEnvironmentVariables.d.ts +49 -8
  58. package/dist/types/models/INodeOptions.d.ts +13 -3
  59. package/dist/types/models/IProtocolHandlerResult.d.ts +13 -0
  60. package/dist/types/models/moduleProtocol.d.ts +29 -0
  61. package/dist/types/models/nodeExtensionMethods.d.ts +2 -2
  62. package/dist/types/models/nodeFeatures.d.ts +5 -5
  63. package/dist/types/node.d.ts +17 -7
  64. package/dist/types/server.d.ts +7 -6
  65. package/dist/types/utils.d.ts +69 -2
  66. package/docs/changelog.md +7 -0
  67. package/docs/detailed-guide.md +129 -0
  68. package/docs/reference/functions/bootstrap.md +1 -1
  69. package/docs/reference/functions/bootstrapAuth.md +1 -1
  70. package/docs/reference/functions/bootstrapBlobEncryption.md +1 -1
  71. package/docs/reference/functions/bootstrapContextIdHandlers.md +35 -0
  72. package/docs/reference/functions/bootstrapImmutableProofMethod.md +1 -1
  73. package/docs/reference/functions/{bootstrapNodeUser.md → bootstrapNodeAdminUser.md} +3 -3
  74. package/docs/reference/functions/{bootstrapNodeIdentity.md → bootstrapNodeId.md} +3 -3
  75. package/docs/reference/functions/bootstrapSynchronisedStorage.md +1 -1
  76. package/docs/reference/functions/bootstrapTenantId.md +35 -0
  77. package/docs/reference/functions/buildConfiguration.md +2 -2
  78. package/docs/reference/functions/buildEngineConfiguration.md +7 -1
  79. package/docs/reference/functions/buildEngineServerConfiguration.md +7 -1
  80. package/docs/reference/functions/createModuleImportUrl.md +21 -0
  81. package/docs/reference/functions/getExtensionsCacheDir.md +31 -0
  82. package/docs/reference/functions/handleHttpsProtocol.md +49 -0
  83. package/docs/reference/functions/handleNpmProtocol.md +31 -0
  84. package/docs/reference/functions/hashUrl.md +19 -0
  85. package/docs/reference/functions/isCacheExpired.md +31 -0
  86. package/docs/reference/functions/overrideModuleImport.md +8 -2
  87. package/docs/reference/functions/parseModuleProtocol.md +19 -0
  88. package/docs/reference/functions/resolvePackageEntryPoint.md +32 -0
  89. package/docs/reference/functions/run.md +3 -3
  90. package/docs/reference/functions/start.md +8 -2
  91. package/docs/reference/index.md +18 -2
  92. package/docs/reference/interfaces/ICacheMetadata.md +27 -0
  93. package/docs/reference/interfaces/IEngineEnvironmentVariables.md +24 -9
  94. package/docs/reference/interfaces/IEngineServerEnvironmentVariables.md +36 -13
  95. package/docs/reference/interfaces/IModuleProtocol.md +27 -0
  96. package/docs/reference/interfaces/INodeEngineConfig.md +430 -0
  97. package/docs/reference/interfaces/INodeEngineState.md +39 -0
  98. package/docs/reference/interfaces/INodeEnvironmentVariables.md +149 -24
  99. package/docs/reference/interfaces/INodeOptions.md +21 -1
  100. package/docs/reference/interfaces/IProtocolHandlerResult.md +19 -0
  101. package/docs/reference/type-aliases/ModuleProtocol.md +5 -0
  102. package/docs/reference/variables/ModuleProtocol.md +37 -0
  103. package/docs/reference/variables/NodeFeatures.md +7 -7
  104. package/locales/en.json +20 -8
  105. package/package.json +40 -8
  106. package/dist/cjs/index.cjs +0 -2232
  107. package/dist/esm/index.mjs +0 -2179
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Metadata for cached HTTPS extensions.
3
+ */
4
+ export interface ICacheMetadata {
5
+ /**
6
+ * Timestamp when the file was downloaded.
7
+ */
8
+ downloadedAt: number;
9
+ /**
10
+ * Original URL of the cached file.
11
+ */
12
+ url: string;
13
+ /**
14
+ * Size of the cached file in bytes.
15
+ */
16
+ size: number;
17
+ }
@@ -14,6 +14,18 @@ export interface IEngineEnvironmentVariables {
14
14
  * The name of the state file.
15
15
  */
16
16
  stateFilename?: string;
17
+ /**
18
+ * Is multi-tenant support enabled, defaults to false.
19
+ */
20
+ tenantEnabled?: string;
21
+ /**
22
+ * A tenant id to use as a default for the node.
23
+ */
24
+ tenantId?: string;
25
+ /**
26
+ * A tenant api key to use as a default for the node.
27
+ */
28
+ tenantApiKey?: string;
17
29
  /**
18
30
  * The type of the entity storage to create, comma separate for more than one connector.
19
31
  * values: file, memory, aws-dynamodb, azure-cosmosdb, gcp-firestoredb, scylladb, mysql, mongodb, postgresql
@@ -285,11 +297,6 @@ export interface IEngineEnvironmentVariables {
285
297
  * Are the messaging components enabled, defaults to false.
286
298
  */
287
299
  messagingEnabled?: string;
288
- /**
289
- * An initial set of templates for the messages.
290
- * Use the @json: prefix to specify the path to the JSON file.
291
- */
292
- messagingTemplates?: string;
293
300
  /**
294
301
  * AWS SES region.
295
302
  */
@@ -1,4 +1,4 @@
1
- import type { IEngineEnvironmentVariables } from "./IEngineEnvironmentVariables";
1
+ import type { IEngineEnvironmentVariables } from "./IEngineEnvironmentVariables.js";
2
2
  /**
3
3
  * The engine server environment variables.
4
4
  */
@@ -0,0 +1,18 @@
1
+ import type { ModuleProtocol } from "./moduleProtocol.js";
2
+ /**
3
+ * The parsed module protocol information.
4
+ */
5
+ export interface IModuleProtocol {
6
+ /**
7
+ * The protocol type.
8
+ */
9
+ protocol: ModuleProtocol;
10
+ /**
11
+ * The identifier after the protocol (or the original if no protocol).
12
+ */
13
+ identifier: string;
14
+ /**
15
+ * The original module string.
16
+ */
17
+ original: string;
18
+ }
@@ -0,0 +1,22 @@
1
+ import type { IEngineState } from "@twin.org/engine-models";
2
+ /**
3
+ * The engine state for the node.
4
+ */
5
+ export interface INodeEngineState extends IEngineState {
6
+ /**
7
+ * The identity for the node.
8
+ */
9
+ nodeId?: string;
10
+ /**
11
+ * The tenant id for the node.
12
+ */
13
+ nodeTenantId?: string;
14
+ /**
15
+ * The identity for the organization.
16
+ */
17
+ nodeOrganizationId?: string;
18
+ /**
19
+ * The identity for the admin user.
20
+ */
21
+ nodeAdminUserId?: string;
22
+ }
@@ -1,28 +1,69 @@
1
- import type { IEngineServerEnvironmentVariables } from "./IEngineServerEnvironmentVariables";
1
+ import type { IEngineServerEnvironmentVariables } from "./IEngineServerEnvironmentVariables.js";
2
2
  /**
3
3
  * The environment variables for the node.
4
4
  */
5
5
  export interface INodeEnvironmentVariables extends IEngineServerEnvironmentVariables {
6
6
  /**
7
7
  * The features that are enabled on the node.
8
- * @default [NodeFeatures.NodeIdentity]
8
+ * @default []
9
9
  */
10
10
  features?: string;
11
11
  /**
12
12
  * The identity of the node which, if empty and node-identity feature is enabled it will be generated.
13
13
  */
14
- identity?: string;
14
+ nodeIdentity?: string;
15
15
  /**
16
16
  * The mnemonic for the identity, if empty and node-identity feature is enabled it will be randomly generated.
17
17
  */
18
- mnemonic?: string;
18
+ nodeMnemonic?: string;
19
19
  /**
20
- * If the node-user feature is enabled, this will be the name of the user.
20
+ * If the node-admin-user feature is enabled, this will be the organization of the user, if one is not provided it will be generated
21
+ */
22
+ organizationIdentity?: string;
23
+ /**
24
+ * The mnemonic for the organization, if empty and node-admin-user feature is enabled it will be randomly generated.
25
+ */
26
+ organizationMnemonic?: string;
27
+ /**
28
+ * If the node-admin-user feature is enabled, this will be the identity of the user, if one is not provided it will be generated
29
+ */
30
+ adminUserIdentity?: string;
31
+ /**
32
+ * The mnemonic for the admin user, if empty and node-admin-user feature is enabled it will be randomly generated.
33
+ */
34
+ adminUserMnemonic?: string;
35
+ /**
36
+ * If the node-admin-user feature is enabled, this will be the name of the user.
21
37
  * @default admin@node
22
38
  */
23
- username?: string;
39
+ adminUserName?: string;
40
+ /**
41
+ * If the node-admin-user feature is enabled, this will be the password of the user, if empty it will be randomly generated.
42
+ */
43
+ adminUserPassword?: string;
44
+ /**
45
+ * Maximum size in MB for HTTPS extensions downloads.
46
+ * @default 10
47
+ */
48
+ extensionsMaxSizeMb?: number;
49
+ /**
50
+ * Whether to clear the extensions cache on startup.
51
+ * @default false
52
+ */
53
+ extensionsClearCache?: boolean;
54
+ /**
55
+ * Custom directory for extensions cache storage.
56
+ * @default ".tmp"
57
+ */
58
+ extensionsCacheDirectory?: string;
59
+ /**
60
+ * TTL in hours for HTTPS extensions cache.
61
+ * @default 24
62
+ */
63
+ extensionsCacheTtlHours?: number;
24
64
  /**
25
- * If the node-user feature is enabled, this will be the password of the user, if empty it will be randomly generated.
65
+ * Force refresh of all cached extensions.
66
+ * @default false
26
67
  */
27
- password?: string;
68
+ extensionsForceRefresh?: boolean;
28
69
  }
@@ -1,7 +1,7 @@
1
1
  import type { IEngineCore, IEngineServer, IEngineStateStorage } from "@twin.org/engine-models";
2
2
  import type { IEngineConfig } from "@twin.org/engine-types";
3
- import type { INodeEngineConfig } from "./INodeEngineConfig";
4
- import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables";
3
+ import type { INodeEngineConfig } from "./INodeEngineConfig.js";
4
+ import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables.js";
5
5
  /**
6
6
  * The options when running the node.
7
7
  */
@@ -15,12 +15,18 @@ export interface INodeOptions {
15
15
  * The version of the server, defaults to the current version.
16
16
  */
17
17
  serverVersion?: string;
18
+ /**
19
+ * Additional environment variables to set.
20
+ */
21
+ envVars?: {
22
+ [key: string]: string;
23
+ };
18
24
  /**
19
25
  * Additional environment variable filenames to load, defaults to .env.
20
26
  */
21
27
  envFilenames?: string[];
22
28
  /**
23
- * The prefix for environment variables, defaults to "TWIN_NODE_".
29
+ * The prefix for environment variables, defaults to "TWIN_".
24
30
  */
25
31
  envPrefix?: string;
26
32
  /**
@@ -71,4 +77,8 @@ export interface INodeOptions {
71
77
  * If not provided, a default file-based state storage will be used.
72
78
  */
73
79
  stateStorage?: IEngineStateStorage;
80
+ /**
81
+ * Disables process.exit calls on fatal errors and throws instead.
82
+ */
83
+ disableProcessExitOnFailure?: boolean;
74
84
  }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * The result from a protocol handler.
3
+ */
4
+ export interface IProtocolHandlerResult {
5
+ /**
6
+ * The resolved path to the module file.
7
+ */
8
+ resolvedPath: string;
9
+ /**
10
+ * Whether the module was cached.
11
+ */
12
+ cached: boolean;
13
+ }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * The protocol types for modules.
3
+ */
4
+ export declare const ModuleProtocol: {
5
+ /**
6
+ * Local module (starts with . or / or file://).
7
+ */
8
+ readonly Local: "local";
9
+ /**
10
+ * NPM package (starts with npm:).
11
+ */
12
+ readonly Npm: "npm";
13
+ /**
14
+ * HTTPS URL (starts with https://).
15
+ */
16
+ readonly Https: "https";
17
+ /**
18
+ * HTTP URL (starts with http://).
19
+ */
20
+ readonly Http: "http";
21
+ /**
22
+ * Default/standard module resolution.
23
+ */
24
+ readonly Default: "default";
25
+ };
26
+ /**
27
+ * The protocol type for a module.
28
+ */
29
+ export type ModuleProtocol = (typeof ModuleProtocol)[keyof typeof ModuleProtocol];
@@ -1,6 +1,6 @@
1
1
  import type { IEngineCore, IEngineServer } from "@twin.org/engine-models";
2
- import type { INodeEngineConfig } from "./INodeEngineConfig";
3
- import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables";
2
+ import type { INodeEngineConfig } from "./INodeEngineConfig.js";
3
+ import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables.js";
4
4
  /**
5
5
  * The type for the initialise method of an extension module.
6
6
  * @param envVars The environment variables for the node.
@@ -3,15 +3,15 @@
3
3
  */
4
4
  export declare const NodeFeatures: {
5
5
  /**
6
- * NodeIdentity - generates an identity for the node if not provided in config.
6
+ * NodeId - generates an identity for the node if not provided in config.
7
7
  */
8
- readonly NodeIdentity: "node-identity";
8
+ readonly NodeId: "node-identity";
9
9
  /**
10
- * NodeUser - generates a user for the node if not provided in config.
10
+ * NodeAdminUser - generates an admin user for the node if not provided in config.
11
11
  */
12
- readonly NodeUser: "node-user";
12
+ readonly NodeAdminUser: "node-admin-user";
13
13
  /**
14
- * NodeWallet - generates a wallet for the node and funds it when there is a faucet available.
14
+ * NodeWallet - generates wallets for any identities that need them.
15
15
  */
16
16
  readonly NodeWallet: "node-wallet";
17
17
  };
@@ -1,13 +1,21 @@
1
1
  import type { IServerInfo } from "@twin.org/api-models";
2
- import type { INodeEngineConfig } from "./models/INodeEngineConfig";
3
- import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables";
4
- import type { INodeOptions } from "./models/INodeOptions";
2
+ import type { Engine } from "@twin.org/engine";
3
+ import type { EngineServer } from "@twin.org/engine-server";
4
+ import type { IEngineServerConfig } from "@twin.org/engine-server-types";
5
+ import type { INodeEngineConfig } from "./models/INodeEngineConfig.js";
6
+ import type { INodeEngineState } from "./models/INodeEngineState.js";
7
+ import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
8
+ import type { INodeOptions } from "./models/INodeOptions.js";
5
9
  /**
6
10
  * Run the TWIN Node server.
7
11
  * @param nodeOptions Optional configuration options for running the server.
8
- * @returns A promise that resolves when the server is started.
12
+ * @returns A promise that resolves when the server is started containing a shutdown method.
9
13
  */
10
- export declare function run(nodeOptions?: INodeOptions): Promise<void>;
14
+ export declare function run(nodeOptions?: INodeOptions): Promise<{
15
+ engine: Engine<IEngineServerConfig, INodeEngineState>;
16
+ server: EngineServer;
17
+ shutdown: () => Promise<void>;
18
+ } | undefined>;
11
19
  /**
12
20
  * Build the configuration for the TWIN Node server.
13
21
  * @param processEnv The environment variables from the process.
@@ -23,9 +31,11 @@ export declare function buildConfiguration(processEnv: {
23
31
  [id: string]: string | unknown;
24
32
  };
25
33
  nodeEngineConfig: INodeEngineConfig;
34
+ contextIdKeys: string[];
26
35
  }>;
27
36
  /**
28
- * Override module imports to use local files where possible.
37
+ * Override module imports to support protocol-based loading (npm:, https:) and local files.
29
38
  * @param executionDirectory The execution directory for resolving local module paths.
39
+ * @param envVars The environment variables containing extension configuration (optional, uses defaults if not provided).
30
40
  */
31
- export declare function overrideModuleImport(executionDirectory: string): void;
41
+ export declare function overrideModuleImport(executionDirectory: string, envVars?: INodeEnvironmentVariables): void;
@@ -1,19 +1,20 @@
1
1
  import { Engine } from "@twin.org/engine";
2
- import { type IEngineState } from "@twin.org/engine-models";
3
2
  import { EngineServer } from "@twin.org/engine-server";
4
3
  import type { IEngineServerConfig } from "@twin.org/engine-server-types";
5
- import type { INodeEngineConfig } from "./models/INodeEngineConfig";
6
- import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables";
7
- import type { INodeOptions } from "./models/INodeOptions";
4
+ import type { INodeEngineConfig } from "./models/INodeEngineConfig.js";
5
+ import type { INodeEngineState } from "./models/INodeEngineState.js";
6
+ import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
7
+ import type { INodeOptions } from "./models/INodeOptions.js";
8
8
  /**
9
9
  * Start the engine server.
10
10
  * @param nodeOptions Optional run options for the engine server.
11
11
  * @param nodeEngineConfig The configuration for the engine server.
12
12
  * @param envVars The environment variables.
13
+ * @param contextIdKeys The context ID keys.
13
14
  * @returns The engine server.
14
15
  */
15
- export declare function start(nodeOptions: INodeOptions | undefined, nodeEngineConfig: INodeEngineConfig, envVars: INodeEnvironmentVariables): Promise<{
16
- engine: Engine<IEngineServerConfig, IEngineState>;
16
+ export declare function start(nodeOptions: INodeOptions | undefined, nodeEngineConfig: INodeEngineConfig, envVars: INodeEnvironmentVariables, contextIdKeys?: string[]): Promise<{
17
+ engine: Engine<IEngineServerConfig, INodeEngineState>;
17
18
  server: EngineServer;
18
19
  shutdown: () => Promise<void>;
19
20
  } | undefined>;
@@ -1,5 +1,8 @@
1
- import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables";
2
- import { NodeFeatures } from "./models/nodeFeatures";
1
+ import type { IModuleProtocol } from "./models/IModuleProtocol.js";
2
+ import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
3
+ import type { IProtocolHandlerResult } from "./models/IProtocolHandlerResult.js";
4
+ import { ModuleProtocol } from "./models/moduleProtocol.js";
5
+ import { NodeFeatures } from "./models/nodeFeatures.js";
3
6
  /**
4
7
  * Initialise the locales for the application.
5
8
  * @param localesDirectory The directory containing the locales.
@@ -52,3 +55,67 @@ export declare function loadJsonFile<T>(filename: string): Promise<T>;
52
55
  * @returns The features that are enabled on the node.
53
56
  */
54
57
  export declare function getFeatures(env: INodeEnvironmentVariables): NodeFeatures[];
58
+ /**
59
+ * Parse the protocol from a module name.
60
+ * @param moduleName The module name to parse.
61
+ * @returns The parsed protocol information.
62
+ */
63
+ export declare function parseModuleProtocol(moduleName: string): IModuleProtocol;
64
+ /**
65
+ * Hash a URL to create a safe filename.
66
+ * @param url The URL to hash.
67
+ * @returns A hashed filename safe for the filesystem.
68
+ */
69
+ export declare function hashUrl(url: string): string;
70
+ /**
71
+ * Get the extensions cache directory.
72
+ * @param executionDirectory The execution directory.
73
+ * @param protocol The protocol type for subdirectory organization.
74
+ * @param cacheDirectory The cache directory base path.
75
+ * @returns The cache directory path.
76
+ */
77
+ export declare function getExtensionsCacheDir(executionDirectory: string, protocol: ModuleProtocol, cacheDirectory?: string): string;
78
+ /**
79
+ * Handle the npm: protocol by installing the package if needed.
80
+ * @param packageName The npm package name (without npm: prefix).
81
+ * @param executionDirectory The execution directory.
82
+ * @param cacheDirectory The cache directory base path.
83
+ * @returns The resolved path to the installed module.
84
+ */
85
+ export declare function handleNpmProtocol(packageName: string, executionDirectory: string, cacheDirectory?: string): Promise<IProtocolHandlerResult>;
86
+ /**
87
+ * Check if a cached file has expired based on TTL and force refresh settings.
88
+ * @param metadataPath Path to the cache metadata file.
89
+ * @param ttlHours Time to live in hours.
90
+ * @param forceRefresh Whether to force refresh regardless of TTL.
91
+ * @returns True if the cache is expired or should be refreshed.
92
+ */
93
+ export declare function isCacheExpired(metadataPath: string, ttlHours: number, forceRefresh: boolean): Promise<boolean>;
94
+ /**
95
+ * Handle the https: protocol by downloading the module if needed.
96
+ * @param url The HTTPS URL to download from.
97
+ * @param executionDirectory The execution directory.
98
+ * @param maxSizeMb The maximum size in MB for the download.
99
+ * @param cacheDirectory The cache directory base path.
100
+ * @param ttlHours TTL in hours for cache expiration.
101
+ * @param forceRefresh Whether to force refresh the cache.
102
+ * @returns The resolved path to the downloaded module.
103
+ */
104
+ export declare function handleHttpsProtocol(url: string, executionDirectory: string, maxSizeMb: number, cacheDirectory?: string, ttlHours?: number, forceRefresh?: boolean): Promise<IProtocolHandlerResult>;
105
+ /**
106
+ * Resolve the main entry point from a package directory using Node.js resolution with fallback.
107
+ * Uses require.resolve() when possible for standard Node.js behavior, with manual fallback.
108
+ * @param packagePath The absolute path to the package directory.
109
+ * @param packageName The package name for require.resolve().
110
+ * @param fallback The fallback file name if no entry point is found.
111
+ * @returns The resolved entry point file name (relative to package directory).
112
+ */
113
+ export declare function resolvePackageEntryPoint(packagePath: string, packageName: string, fallback?: string): Promise<string>;
114
+ /**
115
+ * Convert a file path to an import-compatible URL for cross-platform module loading.
116
+ * On Windows, adds the 'file://' protocol prefix required for dynamic imports.
117
+ * On other platforms, returns the path unchanged.
118
+ * @param filePath The absolute file path to convert.
119
+ * @returns A URL string compatible with dynamic import().
120
+ */
121
+ export declare function createModuleImportUrl(filePath: string): string;
package/docs/changelog.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # @twin.org/node-core - Changelog
2
2
 
3
+ ## [0.0.2-next.26](https://github.com/twinfoundation/node/compare/node-core-v0.0.2-next.25...node-core-v0.0.2-next.26) (2025-10-10)
4
+
5
+
6
+ ### Features
7
+
8
+ * adding npm and https protocols to load extensions ([#45](https://github.com/twinfoundation/node/issues/45)) ([33940b7](https://github.com/twinfoundation/node/commit/33940b7e771a0c5af32c18d442deb26a8631fd02))
9
+
3
10
  ## [0.0.2-next.25](https://github.com/twinfoundation/node/compare/node-core-v0.0.2-next.24...node-core-v0.0.2-next.25) (2025-10-09)
4
11
 
5
12
 
@@ -0,0 +1,129 @@
1
+ # TWIN Node - Detailed Documentation
2
+
3
+ ## Overview
4
+
5
+ TWIN Node provides the foundational components for running TWIN nodes, including dynamic extension loading, protocol-based module resolution, and lifecycle management.
6
+
7
+ ## Protocol-Based Extension Loading
8
+
9
+ The TWIN Node supports dynamic extension loading from multiple sources:
10
+
11
+ ### Local Files
12
+
13
+ Load extensions from your filesystem:
14
+
15
+ ```bash
16
+ TWIN_EXTENSIONS="./my-extension.mjs"
17
+ ```
18
+
19
+ ### NPM Packages
20
+
21
+ Automatically install and load npm packages:
22
+
23
+ ```bash
24
+ TWIN_EXTENSIONS="npm:@twin.org/package"
25
+ ```
26
+
27
+ ### HTTPS URLs
28
+
29
+ Download and cache remote extensions:
30
+
31
+ ```bash
32
+ TWIN_EXTENSIONS="https://example.com/extension.mjs"
33
+ ```
34
+
35
+ ## Extension Lifecycle Hooks
36
+
37
+ Extensions can implement lifecycle hooks to customize node behavior at different stages:
38
+
39
+ - **`extensionInitialise`** - Called before engine initialization
40
+ - **`extensionInitialiseEngine`** - Called during engine initialization
41
+ - **`extensionInitialiseEngineServer`** - Called during server initialization
42
+ - **`extensionShutdown`** - Called during graceful shutdown
43
+
44
+ ### Example Extension
45
+
46
+ ```javascript
47
+ // my-extension.mjs
48
+ export function extensionInitialise() {
49
+ console.log('Extension initializing...');
50
+ }
51
+
52
+ export function extensionInitialiseEngine(engine) {
53
+ console.log('Configuring engine...');
54
+ // Add custom components, routes, etc.
55
+ }
56
+
57
+ export function extensionInitialiseEngineServer(server) {
58
+ console.log('Configuring server...');
59
+ // Add middleware, routes, etc.
60
+ }
61
+
62
+ export function extensionShutdown() {
63
+ console.log('Extension shutting down...');
64
+ // Cleanup resources
65
+ }
66
+ ```
67
+
68
+ ## Configuration Options
69
+
70
+ ### Cache Management
71
+
72
+ - `TWIN_EXTENSIONS_CACHE_TTL_HOURS` - TTL for HTTPS extensions cache (default: 24)
73
+ - `TWIN_EXTENSIONS_FORCE_REFRESH` - Force refresh all cached extensions (default: false)
74
+ - `TWIN_EXTENSIONS_CACHE_DIRECTORY` - Custom cache directory (default: ".tmp")
75
+
76
+ ### Security
77
+
78
+ - `TWIN_EXTENSIONS_MAX_SIZE_MB` - Maximum size for HTTPS downloads (default: 10)
79
+ - `TWIN_EXTENSIONS_CLEAR_CACHE` - Clear cache on startup (default: false)
80
+
81
+ ## API Reference
82
+
83
+ ### Core Functions
84
+
85
+ #### `overrideModuleImport(executionDirectory, envVars)`
86
+
87
+ Sets up protocol-based module resolution for extensions.
88
+
89
+ #### `buildConfiguration(options)`
90
+
91
+ Builds node configuration from environment variables and options.
92
+
93
+ #### `start(options)`
94
+
95
+ Starts the TWIN node with the specified configuration.
96
+
97
+ ### Utility Functions
98
+
99
+ #### `parseModuleProtocol(moduleName)`
100
+
101
+ Parses module name to determine protocol type (npm, https, local, etc.).
102
+
103
+ #### `handleNpmProtocol(packageName, executionDirectory, cacheDirectory)`
104
+
105
+ Handles installation and resolution of npm packages.
106
+
107
+ #### `handleHttpsProtocol(url, executionDirectory, maxSizeMb, cacheDirectory, ttlHours, forceRefresh)`
108
+
109
+ Handles download and caching of HTTPS extensions.
110
+
111
+ ## Security Considerations
112
+
113
+ - **HTTPS Only**: Remote extensions must use HTTPS protocol
114
+ - **Size Limits**: Downloads are limited by `TWIN_EXTENSIONS_MAX_SIZE_MB`
115
+ - **Cache TTL**: Extensions are automatically refreshed based on TTL
116
+ - **Security Warnings**: Warnings are displayed when loading remote extensions
117
+
118
+ ## Troubleshooting
119
+
120
+ ### Common Issues
121
+
122
+ 1. **Extension not found**: Check that the path/URL is correct and accessible
123
+ 2. **Cache issues**: Use `TWIN_EXTENSIONS_FORCE_REFRESH=true` to force refresh
124
+ 3. **Size limit exceeded**: Increase `TWIN_EXTENSIONS_MAX_SIZE_MB` if needed
125
+ 4. **Network issues**: Ensure HTTPS URLs are accessible and not blocked by firewall
126
+
127
+ ### Debug Mode
128
+
129
+ Set `NODE_ENV=development` for additional debug output during extension loading.
@@ -14,7 +14,7 @@ The engine core for the node.
14
14
 
15
15
  ### context
16
16
 
17
- `IEngineCoreContext`\<`IEngineServerConfig`, `IEngineState`\>
17
+ `IEngineCoreContext`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>
18
18
 
19
19
  The context for the node.
20
20
 
@@ -14,7 +14,7 @@ The engine core for the node.
14
14
 
15
15
  ### context
16
16
 
17
- `IEngineCoreContext`\<`IEngineServerConfig`, `IEngineState`\>
17
+ `IEngineCoreContext`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>
18
18
 
19
19
  The context for the node.
20
20
 
@@ -14,7 +14,7 @@ The engine core for the node.
14
14
 
15
15
  ### context
16
16
 
17
- `IEngineCoreContext`\<`IEngineServerConfig`, `IEngineState`\>
17
+ `IEngineCoreContext`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>
18
18
 
19
19
  The context for the node.
20
20
 
@@ -0,0 +1,35 @@
1
+ # Function: bootstrapContextIdHandlers()
2
+
3
+ > **bootstrapContextIdHandlers**(`engineCore`, `context`, `envVars`, `features`): `Promise`\<`void`\>
4
+
5
+ Bootstrap the context id handlers creating any necessary resources.
6
+
7
+ ## Parameters
8
+
9
+ ### engineCore
10
+
11
+ `IEngineCore`
12
+
13
+ The engine core for the node.
14
+
15
+ ### context
16
+
17
+ `IEngineCoreContext`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>
18
+
19
+ The context for the node.
20
+
21
+ ### envVars
22
+
23
+ [`INodeEnvironmentVariables`](../interfaces/INodeEnvironmentVariables.md)
24
+
25
+ The environment variables for the node.
26
+
27
+ ### features
28
+
29
+ [`NodeFeatures`](../type-aliases/NodeFeatures.md)[]
30
+
31
+ The features that are enabled on the node. The features that are enabled on the node.
32
+
33
+ ## Returns
34
+
35
+ `Promise`\<`void`\>
@@ -14,7 +14,7 @@ The engine core for the node.
14
14
 
15
15
  ### context
16
16
 
17
- `IEngineCoreContext`\<`IEngineServerConfig`, `IEngineState`\>
17
+ `IEngineCoreContext`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>
18
18
 
19
19
  The context for the node.
20
20