@twin.org/node-core 0.0.3-next.5 → 0.0.3-next.50

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

@@ -6,6 +6,10 @@ export interface IEngineEnvironmentVariables {
      * Start the engine in debug mode.
      */
     debug?: string;
+    /**
+     * Start the engine in silent mode.
+     */
+    silent?: string;
     /**
      * The root directory for storing items like state file.
      */
@@ -15,17 +19,13 @@ export interface IEngineEnvironmentVariables {
      */
     stateFilename?: string;
     /**
-     * Is multi-tenant support enabled, defaults to false.
+     * Does the node have a unique ID, defaults to true.
      */
-    tenantEnabled?: string;
+    nodeIdentityEnabled?: string;
     /**
-     * A tenant id to use as a default for the node.
-     */
-    tenantId?: string;
-    /**
-     * A tenant api key to use as a default for the node.
+     * Is multi-tenant support enabled, defaults to false.
      */
-    tenantApiKey?: string;
+    tenantEnabled?: string;
     /**
      * The type of the entity storage to create, comma separate for more than one connector.
      * values: file, memory, aws-dynamodb, azure-cosmosdb, gcp-firestoredb, scylladb, mysql, mongodb, postgresql
@@ -192,10 +192,6 @@ export interface IEngineEnvironmentVariables {
      * The default blob storage connector to use, defaults to the first one in the list.
      */
     blobStorageConnectorDefault?: string;
-    /**
-     * Blog storage connector which has public access.
-     */
-    blobStorageConnectorPublic?: string;
     /**
      * Enable encryption for the blob storage.
      */
@@ -204,11 +200,6 @@ export interface IEngineEnvironmentVariables {
      * The id of the encryption key for the blob storage.
      */
     blobStorageEncryptionKeyId?: string;
-    /**
-     * A symmetric encryption key for the blob storage, should be ChaCha20Poly1305 in base64 format.
-     * If encryption is enabled but a key is not provided one will be generated.
-     */
-    blobStorageSymmetricEncryptionKey?: string;
     /**
      * A prefix for all the blobs in blob-storage, can be empty.
      */
@@ -273,6 +264,10 @@ export interface IEngineEnvironmentVariables {
      * The type of the default vault connector: entity-storage, hashicorp.
      */
     vaultConnector?: string;
+    /**
+     * Prefix to prepend to entries in the vault.
+     */
+    vaultPrefix?: string;
     /**
      * Hashicorp Vault token.
      */
@@ -285,10 +280,6 @@ export interface IEngineEnvironmentVariables {
      * The type of logging task connector, can be a comma separated list: console, entity-storage.
      */
     loggingConnector?: string;
-    /**
-     * The type of background task connector: entity-storage.
-     */
-    backgroundTaskConnector?: string;
     /**
      * The type of event bus connector: local.
      */
@@ -322,7 +313,7 @@ export interface IEngineEnvironmentVariables {
      */
     awsSesEndpoint?: string;
     /**
-     * The applications for the push notifications JSON stringified array of IAwsApplicationSettings.
+     * The applications for the push notifications reference a separate json with @json: prefix.
      */
     awsMessagingPushNotificationApplications?: string;
     /**
@@ -341,6 +332,34 @@ export interface IEngineEnvironmentVariables {
      * The type of telemetry connector: entity-storage.
      */
     telemetryConnector?: string;
+    /**
+     * The name of the Open Telemetry meter to use, only required if using open-telemetry as telemetry connector, defaults to twin-node.
+     */
+    openTelemetryMeterName?: string;
+    /**
+     * The version of the Open Telemetry metrics specification to use, only required if using open-telemetry as telemetry connector, defaults to 1.0.0.
+     */
+    openTelemetryMeterVersion?: string;
+    /**
+     * The type of Open Telemetry metric reader to use, only required if using open-telemetry as telemetry connector, values: prometheus.
+     */
+    openTelemetryReader?: string;
+    /**
+     * The port to use for the Open Telemetry Prometheus metrics server, only required if using open-telemetry as telemetry connector and prometheus as reader, defaults to 9464.
+     */
+    openTelemetryPrometheusPort?: string;
+    /**
+     * Polling interval in seconds for the telemetry metrics collector. Defaults to 60.
+     */
+    telemetryMetricsCollectorIntervalSeconds?: string;
+    /**
+     * The type of telemetry metrics producers, can be a comma separated list: system, process.
+     */
+    telemetryMetricsProducers?: string;
+    /**
+     * Maximum number of values retained per telemetry metric (count-based history cap). Defaults to 1440.
+     */
+    telemetryMetricsProducerMaxHistory?: string;
     /**
      * The type of faucet connector: entity-storage, iota.
      */
@@ -353,18 +372,26 @@ export interface IEngineEnvironmentVariables {
      * The type of NFT connector: entity-storage, iota.
      */
     nftConnector?: string;
+    /**
+     * The NFT deployed package id, for custom deployments.
+     */
+    nftPackageId?: string;
+    /**
+     * The type of notarization connector: entity-storage, iota.
+     */
+    notarizationConnector?: string;
     /**
      * The type of identity connector: entity-storage, iota.
      */
     identityConnector?: string;
     /**
-     * The type of identity resolver connector: entity-storage, iota.
+     * The index of the wallet address to use, defaults to 0.
      */
-    identityResolverConnector?: string;
+    identityWalletAddressIndex?: string;
     /**
-     * The type of verifiable storage connector: entity-storage, iota.
+     * The type of identity resolver connector: entity-storage, iota.
      */
-    verifiableStorageConnector?: string;
+    identityResolverConnector?: string;
     /**
      * IOTA Faucet Endpoint.
      */
@@ -393,6 +420,10 @@ export interface IEngineEnvironmentVariables {
      * IOTA Gas Station Authentication Token.
      */
     iotaGasStationAuthToken?: string;
+    /**
+     * The IOTA Identity deployed package id, for custom deployments.
+     */
+    iotaIdentityPackageId?: string;
     /**
      * Universal Resolver Endpoint.
      */
@@ -438,131 +469,125 @@ export interface IEngineEnvironmentVariables {
      */
     documentManagementEnabled?: string;
     /**
-     * Is the synchronised storage enabled, defaults to false.
+     * Enable the federated catalogue, defaults to false, automatically enabled if remote endpoint, filters or dataspace is enabled.
      */
-    synchronisedStorageEnabled?: string;
+    federatedCatalogueEnabled?: string;
     /**
-     * Url which points to the api for a trusted synchronised storage node, not required if this is a trusted node.
+     * Federated catalog filters, command separated list of filters to add.
      */
-    synchronisedStorageTrustedUrl?: string;
+    federatedCatalogueFilters?: 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 to the network name.
+     * Federated catalog remote endpoint, if set will use a REST client instead of local service.
      */
-    synchronisedStorageVerifiableStorageKeyId?: string;
+    federatedCatalogueRemoteEndpoint?: string;
     /**
-     * The key from the vault which is used to encrypt the synchronised storage blobs.
-     * Only required for trusted nodes, as regular nodes will request from the trusted nodes.
-     * Defaults to synchronised-storage-blob-encryption
+     * The trust generators to add to the factory, comma separated list.
      */
-    synchronisedStorageBlobStorageEncryptionKeyId?: string;
+    trustGenerators?: string;
     /**
-     * The key used for blob encryption, should be ChaCha20Poly1305 encoded as base64.
-     * Only required for trusted nodes, as regular nodes will not write encrypted data.
+     * The trust verifiers to add to the factory, comma separated list.
      */
-    synchronisedStorageBlobStorageKey?: string;
+    trustVerifiers?: string;
     /**
-     * How often to check for entity updates in minutes.
-     * @default 5
+     * The verification method to use for trust identities.
+     * Defaults to trust-assertion.
      */
-    synchronisedStorageEntityUpdateIntervalMinutes?: string;
+    trustVerificationMethodId?: string;
     /**
-     * Interval to perform consolidation of changesets, only used if this is a trusted node.
-     * @default 60
+     * The trust time to live for generating JWTs.
+     * Defaults to undefined for never expiring.
      */
-    synchronisedStorageConsolidationIntervalMinutes?: string;
+    trustJwtTtlSeconds?: string;
     /**
-     * The number of entities to process in a single consolidation batch, only used if this is a trusted node.
-     * @default 1000
+     * The allow lists for the trust identity verifier, comma separated list of identities.
      */
-    synchronisedStorageConsolidationBatchSize?: string;
+    trustIdentitiesAllow?: string;
     /**
-     * The maximum number of consolidations to keep in storage, only used if this is a trusted node.
-     * @default 5
+     * The deny lists for the trust identity verifier, comma separated list of identities.
      */
-    synchronisedStorageMaxConsolidations?: string;
+    trustIdentitiesDeny?: string;
     /**
-     * Is the federated catalogue enabled, defaults to false.
+     * Path under which the rights management service is mounted (single source
+     * of truth). The same value drives:
+     * - the server route mount (via engine config)
+     * - the PNP service's callback URL builder (`buildCallbackUrl`)
+     * - the PNP rest-client's pathPrefix (consumer side)
+     * Defaults to `rights-management`. Set when deploying behind a reverse proxy
+     * with path rewriting, K8s ingress with path-based routing, or any custom
+     * mount point.
      */
-    federatedCatalogueEnabled?: string;
+    rightsManagementCallbackPath?: string;
     /**
-     * Federated catalog TTL for the cache.
+     * The rights management policy information sources to add to the factory.
      */
-    federatedCatalogueCacheTtlMs?: number;
+    rightsManagementPolicyInformationSources?: string;
     /**
-     * Federated catalog clearing house approver list, stringified array of DIDs.
+     * The rights management policy negotiators sources to add to the factory.
      */
-    federatedCatalogueClearingHouseApproverList?: string;
+    rightsManagementPolicyNegotiators?: string;
     /**
-     * Is the rights management enabled, defaults to false.
+     * The rights management policy requesters to add to the factory.
      */
-    rightsManagementEnabled?: string;
+    rightsManagementPolicyRequesters?: string;
     /**
-     * What is the base callback url for rights management negotiations e.g. https://my-node/rights-management.
+     * The rights management policy execution actions to add to the factory.
      */
-    rightsManagementBaseCallbackUrl?: string;
+    rightsManagementPolicyExecutionActions?: string;
     /**
-     * The rights management configuration which includes the information sources modules to load.
-     * Use the @json: prefix to specify the path to the JSON configuration file.
+     * The rights management policy enforcement processors to add to the factory.
      */
-    rightsManagementInformationSources?: string;
+    rightsManagementPolicyEnforcementProcessors?: string;
     /**
-     * The rights management configuration which includes the negotiator modules to load.
-     * Use the @json: prefix to specify the path to the JSON configuration file.
+     * The rights management policy arbiters to add to the factory.
      */
-    rightsManagementNegotiators?: string;
+    rightsManagementPolicyArbiters?: string;
     /**
-     * The rights management configuration which includes the requester modules to load.
-     * Use the @json: prefix to specify the path to the JSON configuration file.
+     * The rights management policy obligation enforcers to add to the factory.
      */
-    rightsManagementRequesters?: string;
+    rightsManagementPolicyObligationEnforcers?: string;
     /**
-     * The rights management configuration which includes the execution actions modules to load.
-     * Use the @json: prefix to specify the path to the JSON configuration file.
+     * Is the dataspace enabled, defaults to false.
      */
-    rightsManagementExecutionActions?: string;
+    dataspaceEnabled?: string;
     /**
-     * The rights management configuration which includes the enforcement processor modules to load.
-     * Use the @json: prefix to specify the path to the JSON configuration file.
-     */
-    rightsManagementEnforcementProcessors?: string;
-    /**
-     * The rights management configuration which includes the arbiter modules to load.
-     * 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
      */
-    rightsManagementArbiters?: string;
+    dataspaceRetainActivityLogsFor?: string;
     /**
-     * The rights management configuration which includes the offer modules to load.
-     * Use the @json: prefix to specify the path to the JSON configuration file.
+     * The interval for cleaning up the activity logs.
+     * @default 60
      */
-    rightsManagementOffers?: string;
+    dataspaceActivityLogsCleanUpInterval?: string;
     /**
-     * Is the task scheduler enabled, defaults to false.
+     * The data plane path for PULL transfers (path only, not full URL).
+     * Will be combined with public origin from hosting component.
+     * Required if PULL transfers should be supported.
+     * Example: "dataspace/entities"
      */
-    taskSchedulerEnabled?: string;
+    dataspaceDataPlanePath?: string;
     /**
-     * Is the data space connector enabled, defaults to false.
+     * Are the health components enabled, defaults to false.
      */
-    dataSpaceConnectorEnabled?: string;
+    healthEnabled?: string;
     /**
-     * The length of time to retain the activity logs for in minutes, set to -1 to keep forever.
-     * @default 10
+     * The interval in seconds for performing health checks, defaults to 60.
      */
-    dataSpaceConnectorRetainActivityLogsFor?: string;
+    healthIntervalSeconds?: string;
     /**
-     * The interval for cleaning up the activity logs.
-     * @default 60
+     * The interval in seconds for performing health checks at startup, defaults to 2.
+     * This allows components that take a long time to initialize to be healthy before the first health check is performed.
      */
-    dataSpaceConnectorActivityLogsCleanUpInterval?: string;
+    healthStartupIntervalSeconds?: string;
     /**
-     * Enable verifiable credential authentication for the API.
+     * The id of the key in the vault to use for encrypting parameters in url transformer.
      */
-    vcAuthenticationEnabled?: string;
+    urlTransformerEncryptionKeyId?: string;
     /**
-     * Verifiable credential assertion for node to node communication.
-     * Defaults to node-authentication-assertion.
+     * The type of the automation action to create, comma separate for more than one connector.
+     * values: fetch
      */
-    vcAuthenticationVerificationMethodId?: string;
+    automationActionTypes?: string;
     /**
      * A comma separated list of additional node extensions to load, the initialiseExtension method will be called for each extension.
      */

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

@@ -27,6 +27,10 @@ export interface IEngineServerEnvironmentVariables extends IEngineEnvironmentVar
      * The CORS headers to expose.
      */
     httpExposedHeaders?: string;
+    /**
+     * The public origin URL for the API e.g. https://api.example.com:1234
+     */
+    publicOrigin?: string;
     /**
      * The type of auth admin processor to use on the API: entity-storage.
      */
@@ -39,6 +43,10 @@ export interface IEngineServerEnvironmentVariables extends IEngineEnvironmentVar
      * The id of the key in the vault to use for signing in auth operations.
      */
     authSigningKeyId?: string;
+    /**
+     * The id of the key in the vault to use for encrypting hosting parameters in auth operations.
+     */
+    hostingParamEncryptionKeyId?: string;
     /**
      * Additional MIME type processors to include, comma separated.
      */

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

@@ -7,16 +7,4 @@ export interface INodeEngineState extends IEngineState {
      * The identity for the node.
      */
     nodeId?: string;
-    /**
-     * The tenant id for the node.
-     */
-    nodeTenantId?: string;
-    /**
-     * The identity for the organization.
-     */
-    nodeOrganizationId?: string;
-    /**
-     * The identity for the admin user.
-     */
-    nodeAdminUserId?: string;
 }

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

@@ -3,44 +3,6 @@ import type { IEngineServerEnvironmentVariables } from "./IEngineServerEnvironme
  * The environment variables for the node.
  */
 export interface INodeEnvironmentVariables extends IEngineServerEnvironmentVariables {
-    /**
-     * The features that are enabled on the node.
-     * @default []
-     */
-    features?: string;
-    /**
-     * The identity of the node which, if empty and node-identity feature is enabled it will be generated.
-     */
-    nodeIdentity?: string;
-    /**
-     * The mnemonic for the identity, if empty and node-identity feature is enabled it will be randomly generated.
-     */
-    nodeMnemonic?: string;
-    /**
-     * 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
-     */
-    organizationIdentity?: string;
-    /**
-     * The mnemonic for the organization, if empty and node-admin-user feature is enabled it will be randomly generated.
-     */
-    organizationMnemonic?: string;
-    /**
-     * 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
-     */
-    adminUserIdentity?: string;
-    /**
-     * The mnemonic for the admin user, if empty and node-admin-user feature is enabled it will be randomly generated.
-     */
-    adminUserMnemonic?: string;
-    /**
-     * If the node-admin-user feature is enabled, this will be the name of the user.
-     * @default admin@node
-     */
-    adminUserName?: string;
-    /**
-     * If the node-admin-user feature is enabled, this will be the password of the user, if empty it will be randomly generated.
-     */
-    adminUserPassword?: string;
     /**
      * Maximum size in MB for HTTPS extensions downloads.
      * @default 10

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

@@ -7,8 +7,8 @@ import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables.js";
  */
 export interface INodeOptions {
     /**
-     * The name of the server, defaults to "TWIN Node Server".
-     * @default "TWIN Node Server"
+     * The name of the server, defaults to "TWIN Node".
+     * @default "TWIN Node"
      */
     serverName?: string;
     /**
@@ -40,6 +40,10 @@ export interface INodeOptions {
      * This will be merged with any configuration loaded from the environment variables.
      */
     config?: IEngineConfig;
+    /**
+     * The directory to override the script location, defaults to location of index.js.
+     */
+    scriptDirectory?: string;
     /**
      * The directory to override the execution location, defaults to process directory.
      */

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

@@ -0,0 +1,4 @@
+/**
+ * Type for the properties in commands.
+ */
+export type CliCommandParamType = string | number | boolean;

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

@@ -0,0 +1,7 @@
+import type { IEngineCore } from "@twin.org/engine-models";
+/**
+ * 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>;

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

@@ -0,0 +1,8 @@
+import type { IEngineCore, IEngineServer } from "@twin.org/engine-models";
+/**
+ * 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>;

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

@@ -0,0 +1,8 @@
+import type { INodeEngineConfig } from "./INodeEngineConfig.js";
+import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables.js";
+/**
+ * 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>;

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

@@ -0,0 +1,5 @@
+/**
+ * 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

@@ -7,17 +7,18 @@ import type { INodeEngineState } from "./models/INodeEngineState.js";
 import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
 import type { INodeOptions } from "./models/INodeOptions.js";
 /**
- * Run the TWIN Node server.
+ * Run the TWIN Node.
  * @param nodeOptions Optional configuration options for running the server.
+ * @param args Optional command line arguments.
  * @returns A promise that resolves when the server is started containing a shutdown method.
  */
-export declare function run(nodeOptions?: INodeOptions): Promise<{
+export declare function run(nodeOptions?: INodeOptions, args?: string[]): Promise<{
     engine: Engine<IEngineServerConfig, INodeEngineState>;
     server: EngineServer;
     shutdown: () => Promise<void>;
 } | undefined>;
 /**
- * Build the configuration for the TWIN Node server.
+ * Build the configuration for the TWIN Node.
  * @param processEnv The environment variables from the process.
  * @param options The options for running the server.
  * @param serverInfo The server information.
@@ -33,7 +34,7 @@ export declare function buildConfiguration(processEnv: {
     nodeEngineConfig: INodeEngineConfig;
     availableContextIdKeys: {
         key: string;
-        componentFeatures: string[];
+        requiredHandlerFeatures: string[];
     }[];
 }>;
 /**

package/dist/types/{server.d.ts → start.d.ts}

@@ -1,6 +1,7 @@
 import { Engine } from "@twin.org/engine";
 import { EngineServer } from "@twin.org/engine-server";
 import type { IEngineServerConfig } from "@twin.org/engine-server-types";
+import type { ICliCommand } from "./models/ICliCommand.js";
 import type { INodeEngineConfig } from "./models/INodeEngineConfig.js";
 import type { INodeEngineState } from "./models/INodeEngineState.js";
 import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
@@ -10,12 +11,13 @@ import type { INodeOptions } from "./models/INodeOptions.js";
  * @param nodeOptions Optional run options for the engine server.
  * @param nodeEngineConfig The configuration for the engine server.
  * @param envVars The environment variables.
+ * @param cliCommand The constructed CLI command (optional).
  * @param availableContextIdKeys The context ID keys available for operation.
  * @returns The engine server.
  */
-export declare function start(nodeOptions: INodeOptions | undefined, nodeEngineConfig: INodeEngineConfig, envVars: INodeEnvironmentVariables, availableContextIdKeys?: {
+export declare function start(nodeOptions: INodeOptions | undefined, nodeEngineConfig: INodeEngineConfig, envVars: INodeEnvironmentVariables, cliCommand?: ICliCommand, availableContextIdKeys?: {
     key: string;
-    componentFeatures: string[];
+    requiredHandlerFeatures: string[];
 }[]): Promise<{
     engine: Engine<IEngineServerConfig, INodeEngineState>;
     server: EngineServer;

package/dist/types/utils.d.ts

@@ -1,8 +1,6 @@
 import type { IModuleProtocol } from "./models/IModuleProtocol.js";
-import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
 import type { IProtocolHandlerResult } from "./models/IProtocolHandlerResult.js";
 import { ModuleProtocol } from "./models/moduleProtocol.js";
-import { NodeFeatures } from "./models/nodeFeatures.js";
 /**
  * Initialise the locales for the application.
  * @param localesDirectory The directory containing the locales.
@@ -13,6 +11,12 @@ export declare function initialiseLocales(localesDirectory: string): Promise<voi
  * @returns The execution directory.
  */
 export declare function getExecutionDirectory(): string;
+/**
+ * Get the directory where the script is located.
+ * @param args The command line arguments.
+ * @returns The execution directory.
+ */
+export declare function getScriptDirectory(args?: string[]): string;
 /**
  * Does the specified file exist.
  * @param filename The filename to check for existence.
@@ -49,12 +53,6 @@ export declare function loadTextFile(filename: string): Promise<string>;
  * @returns The contents of the JSON file or null if it could not be loaded.
  */
 export declare function loadJsonFile<T>(filename: string): Promise<T>;
-/**
- * Get the features that are enabled on the node.
- * @param env The environment variables for the node.
- * @returns The features that are enabled on the node.
- */
-export declare function getFeatures(env: INodeEnvironmentVariables): NodeFeatures[];
 /**
  * Parse the protocol from a module name.
  * @param moduleName The module name to parse.