### Build and Run TWIN Node Application (Shell)

Source: https://github.com/twinfoundation/node/blob/next/apps/node/README.md

Commands to install dependencies, build the application, and start the server. These are essential steps for setting up and running the TWIN Node.

```shell
npm install
npm run dist
npm start
```

--------------------------------

### Example Extension Implementation

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/configuration.md

A complete example of an extension module (`.mjs`) demonstrating the implementation of all required lifecycle methods: `extensionInitialise`, `extensionInitialiseEngine`, `extensionInitialiseEngineServer`, and `extensionShutdown`.

```typescript
// my-extension.mjs
export async function extensionInitialise(envVars, nodeEngineConfig) {
  console.log('Extension initializing with config');
}

export async function extensionInitialiseEngine(engineCore) {
  engineCore.logInfo('Custom extension loaded');
}

export async function extensionInitialiseEngineServer(engineCore, engineServer) {
  // Add custom routes
  engineServer.addRestRoute({
    path: '/custom/endpoint',
    method: 'GET',
    handler: async () => ({ body: { message: 'Hello from extension!' } })
  });
}

export async function extensionShutdown() {
  console.log('Extension shutting down');
}
```

--------------------------------

### Start Node.js Engine Server

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/docs/reference/functions/start.md

Initiates the engine server using the start() function. This function requires nodeEngineConfig and envVars, and optionally accepts nodeOptions, cliCommand, and availableContextIdKeys. It returns a promise that resolves with the engine, server, and a shutdown function, or undefined if the server cannot be started.

```typescript
import {
  start,
  INodeOptions,
  INodeEngineConfig,
  INodeEnvironmentVariables,
  ICliCommand,
  IEngineServerConfig,
  INodeEngineState,
} from "@twinlog/node";

async function startEngine(
  nodeOptions: INodeOptions | undefined,
  nodeEngineConfig: INodeEngineConfig,
  envVars: INodeEnvironmentVariables,
  cliCommand?: ICliCommand,
  availableContextIdKeys?: object[]
) {
  const result = await start(
    nodeOptions,
    nodeEngineConfig,
    envVars,
    cliCommand,
    availableContextIdKeys
  );

  if (result) {
    const { engine, server, shutdown } = result;
    console.log("Engine server started successfully.");
    // You can now use engine, server, and shutdown
    // Example: await shutdown();
  } else {
    console.error("Failed to start engine server.");
  }
}

```

--------------------------------

### Install and Run TWIN Node

Source: https://context7.com/twinfoundation/node/llms.txt

Instructions for installing the TWIN Node package globally or locally, and running the server in different modes including development with hot reload.

```bash
# Install the package globally
npm install -g @twin.org/node@next

# Or run directly with npx
npx @twin.org/node@next --help

# Install dependencies and run from source
npm install
npm run dist
npm start

# Development mode with hot reload
npm run dev
```

--------------------------------

### TWIN Node Server Startup

Source: https://context7.com/twinfoundation/node/llms.txt

This section details how to start the TWIN Node REST server using the `run()` function, including basic and custom configurations.

```APIDOC
## run() - Start TWIN Node Server

### Description
The main entry point function that initializes and starts the TWIN Node REST server with all configured components.

### Method
```typescript
run(options?: object, args?: string[]): Promise<object | undefined>
```

### Parameters
#### Options Object
- **serverName** (string) - Optional - The name of the server.
- **serverVersion** (string) - Optional - The version of the server.
- **openApiSpecFile** (string) - Optional - Path to the OpenAPI specification file.
- **favIconFile** (string) - Optional - Path to the favicon file.
- **executionDirectory** (string) - Optional - The directory for execution.
- **envPrefix** (string) - Optional - The prefix for environment variables.
- **envVars** (object) - Optional - An object containing environment variables to override.

#### Arguments
- **args** (string[]) - Optional - Command-line arguments.

### Request Example
```typescript
import path from 'node:path';
import { run } from '@twin.org/node-core';

// Basic usage with default options
const result = await run();

// Custom configuration
const result = await run(
  {
    serverName: "My TWIN Node",
    serverVersion: "1.0.0",
    openApiSpecFile: path.resolve('docs/open-api/spec.json'),
    favIconFile: path.resolve('static/favicon.ico'),
    executionDirectory: process.cwd(),
    envPrefix: "TWIN_",
    envVars: {
      TWIN_HOST: "0.0.0.0",
      TWIN_PORT: "3000"
    }
  },
  process.argv
);

// Access server components
if (result) {
  console.log("Server started successfully");

  // Graceful shutdown
  process.on('SIGTERM', async () => {
    await result.shutdown();
    process.exit(0);
  });
}
```

### Response
#### Success Response (200)
- **result** (object) - An object containing server instance and shutdown function if successful.

#### Response Example
```json
{
  "shutdown": "function"
}
```
```

--------------------------------

### Node Run Function

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/docs/reference/functions/run.md

Documentation for the `run()` function, which starts the TWIN Node server.

```APIDOC
## Function: run()

### Description
Runs the TWIN Node server with optional configuration and arguments.

### Method
`run(nodeOptions?, args?): Promise<{
  engine: Engine<IEngineServerConfig, INodeEngineState>;
  server: EngineServer;
  shutdown: () => Promise<void>;
} | undefined>
`

### Parameters
#### nodeOptions?
- **nodeOptions** (`INodeOptions`) - Optional - Optional configuration options for running the server.

#### args?
- **args** (`string[]`) - Optional - Optional command line arguments.

### Returns
- **Promise** (`object | undefined`) - A promise that resolves when the server is started, containing the engine, server instance, and a shutdown method. Resolves with `undefined` if the server fails to start.

### Response Example (Success)
```json
{
  "engine": "<Engine object>",
  "server": "<EngineServer object>",
  "shutdown": "<Function to shut down the server>"
}
```
```

--------------------------------

### Start TWIN Node Server with run()

Source: https://context7.com/twinfoundation/node/llms.txt

The main entry point function to initialize and start the TWIN Node REST server. It supports basic usage with default options or custom configurations for server details, file paths, and environment variables. Includes graceful shutdown handling.

```typescript
import path from 'node:path';
import { run } from '@twin.org/node-core';

// Basic usage with default options
const result = await run();

// Custom configuration
const result = await run(
  {
    serverName: "My TWIN Node",
    serverVersion: "1.0.0",
    openApiSpecFile: path.resolve('docs/open-api/spec.json'),
    favIconFile: path.resolve('static/favicon.ico'),
    executionDirectory: process.cwd(),
    envPrefix: "TWIN_",
    envVars: {
      TWIN_HOST: "0.0.0.0",
      TWIN_PORT: "3000"
    }
  },
  process.argv
);

// Access server components
if (result) {
  console.log("Server started successfully");

  // Graceful shutdown
  process.on('SIGTERM', async () => {
    await result.shutdown();
    process.exit(0);
  });
}
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/twinfoundation/node/blob/next/CONTRIBUTING.md

Instructions for cloning the project repository and installing necessary Node.js dependencies using npm.

```shell
git clone https://github.com/twinfoundation/<repo>.git
cd <repo>
npm install
```

--------------------------------

### Extension API: extensionInitialiseEngine

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/configuration.md

The `extensionInitialiseEngine` function is invoked after the engine is created but before the server starts. Use this to register components or set up services.

```typescript
export async function extensionInitialiseEngine(engineCore: IEngineCore): Promise<void> {
  // Register components, set up services, etc.
}
```

--------------------------------

### Start TWIN Node (JavaScript)

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/docs/detailed-guide.md

Initiates the TWIN Node process with the specified configuration. This is the primary function to start the node and begin processing extensions and requests.

```javascript
start(options);
```

--------------------------------

### Install Git on EC2 Instance

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/deployment-ec2.md

Installs Git on an Amazon Linux EC2 instance using `yum`. This is required for cloning the project repository. It also verifies the installation by printing the Git version.

```shell
sudo yum install git -y
git -version
```

--------------------------------

### Build Project and Verify Setup

Source: https://github.com/twinfoundation/node/blob/next/CONTRIBUTING.md

Commands to perform a full project build, including cleaning, compiling, testing, packaging, and generating documentation. Also includes commands for development tasks like formatting, linting, and watching files.

```shell
# Repository level commands
npm run format
npm run lint
npm run dist

# Package level commands
npm run build
npm run dev
npm run docs
npm run test
npm run test:coverage
npm run dist
```

--------------------------------

### Display twin-node CLI help

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Shows the main help message for the twin-node CLI, listing all available commands and options. This is useful for understanding the overall functionality of the tool.

```shell
twin-node --help
```

```shell
npx "@twin.org/node@next" --help
```

--------------------------------

### Dockerfile for Node.js API Deployment

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/deployment-docker.md

This Dockerfile sets up a Node.js environment for the API server. It installs dependencies, compiles translation messages, prunes development dependencies to reduce image size, exposes the application port, and defines runtime environment variables and the command to start the server.

```shell
# Set the base image
FROM node:22

# Create the app directory
WORKDIR /app

# Copy the package.json
COPY package.json .

# Install dependencies including dev dependencies needed for merge-locales
RUN npm install --ignore-scripts

# Copy the rest of the files to the image
COPY . .

# Compile translation messages
RUN npm run merge-locales

# Remove dev dependencies to reduce image size
RUN npm prune --omit=dev

# Expose the port the app runs on
EXPOSE 3000

# Set the environment variables that will override the .env file in the package
ENV TWIN_HOST=0.0.0.0
ENV TWIN_PORT=3000
ENV TWIN_STORAGE_FILE_ROOT=/twin-node/data

# Start the server
CMD ["node", "src/index.mjs"]
```

--------------------------------

### Create a new tenant for the node

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Provisions a new tenant that the node can interact with. This involves setting a label, a public origin URL for the tenant's API, and outputting the tenant details to JSON and environment files.

```shell
twin-node tenant-create --label="node" --public-origin="https://api.example.com" --output-env-prefix=node --output-json="node-tenant.json" --output-env="node-tenant.env"
```

--------------------------------

### TWIN Node Docker Container Startup Output

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/deployment-docker.md

This is the expected output when the TWIN Node Docker container starts successfully. It includes version information, directory paths, and detailed logging messages indicating the engine's initialization, component loading, and service startup. The output confirms that the engine is starting, debugging is enabled, and state is being loaded from `engine-state.json`.

```shell
🌩️  TWIN Node v1.0.0

Execution Directory: /app
Locales Directory: /app/dist/locales
Locales File: /app/dist/locales/en.json
OpenAPI Spec File: /app/docs/open-api/spec.json
Favicon File: /app/static/favicon.ico
Environment Variable Prefix: TWIN_
Default Environment File: /app/.env

INFO [2025-10-03T01:23:42.634Z] EngineCore Engine is starting
INFO [2025-10-03T01:23:42.635Z] EngineCore Debugging is enabled
INFO [2025-10-03T01:23:42.636Z] EngineCore Loading state from file storage with filename "twin-node/data/engine-state.json"
INFO [2025-10-03T01:23:42.637Z] EngineCore Configuring loggingConnector: console
INFO [2025-10-03T01:23:42.637Z] EngineCore Configuring loggingConnector: entity-storage
INFO [2025-10-03T01:23:42.638Z] EngineCore Configuring Entity Storage with name "log-entry" using "file" connector
INFO [2025-10-03T01:23:42.638Z] EngineCore Configuring loggingConnector: multi
INFO [2025-10-03T01:23:42.638Z] EngineCore Configuring loggingComponent: service
...
INFO [2025-10-03T01:23:42.655Z] EngineCore Bootstrap started
...
INFO [2025-10-03T01:27:34.331Z] EngineCore Wallet already funded
INFO [2025-10-03T01:27:35.064Z] EngineCore Node identity already exists "did:iota:testnet:0xc7aa88cd54c8c90fc1cbe5927b3e2fe33d478ca7b6b058020c0d87e8f88fac82"
INFO [2025-10-03T01:27:35.065Z] EngineCore Identity explorer "https://explorer.iota.org/object/0xc7aa88cd54c8c90fc1cbe5927b3e2fe33d478ca7b6b058020c0d87e8f88fac82?network=testnet"
INFO [2025-10-03T01:27:35.065Z] EngineCore Node identity "did:iota:testnet:0xc7aa88cd54c8c90fc1cbe5927b3e2fe33d478ca7b6b058020c0d87e8f88fac82"
INFO [2025-10-03T01:27:35.066Z] EngineCore Node user already exists "admin@node"
INFO [2025-10-03T01:27:35.066Z] EngineCore User profile already exists "did:iota:testnet:0xc7aa88cd54c8c90fc1cbe5927b3e2fe33d478ca7b6b058020c0d87e8f88fac82"
INFO [2025-10-03T01:27:35.067Z] EngineCore Authentication key already exists "did:iota:testnet:0xc7aa88cd54c8c90fc1cbe5927b3e2fe33d478ca7b6b058020c0d87e8f88fac82/auth-signing"
INFO [2025-10-03T01:27:35.067Z] EngineCore Blob encryption key already exists "did:iota:testnet:0xc7aa88cd54c8c90fc1cbe5927b3e2fe33d478ca7b6b058020c0d87e8f88fac82/blob-encryption"
INFO [2025-10-03T01:27:35.807Z] EngineCore Verification method for attestation already exists "did:iota:testnet:0xc7aa88cd54c8c90fc1cbe5927b3e2fe33d478ca7b6b058020c0d87e8f88fac82#attestation-assertion"
INFO [2025-10-03T01:27:36.512Z] EngineCore Verification method for immutable proof already exists "did:iota:testnet:0xc7aa88cd54c8c90fc1cbe5927b3e2fe33d478ca7b6b058020c0d87e8f88fac82#immutable-proof-assertion"
INFO [2025-10-03T01:27:36.512Z] EngineCore Bootstrap complete
INFO [2025-10-03T01:24:01.773Z] EngineCore Components are starting
...
INFO [2025-10-03T01:24:02.476Z] EngineCore Components have started
INFO [2025-10-03T01:24:02.476Z] EngineCore Engine has started
INFO [2025-10-03T01:24:02.477Z] EngineCore Saving state to file storage with filename "twin-node/data/engine-state.json"
INFO [2025-10-03T01:24:02.496Z] FastifyWebServer Building Web Server
...
INFO [2025-10-03T01:24:03.111Z] FastifyWebServer Starting Web Server at address "0.0.0.0" on port "3000"
INFO [2025-10-03T01:24:03.128Z] FastifyWebServer The Web Server started on http://0.0.0.0:3000
```

--------------------------------

### Import an existing tenant for the node

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Imports details of an existing tenant to be used by the node. This requires loading tenant information from a JSON file and providing the tenant ID, API key, label, and public origin.

```shell
twin-node tenant-import --load-env="node-tenant.json" --tenant-id=!NODE_TENANT_ID --api-key=!NODE_API_KEY --label=!NODE_LABEL --public-origin="https://api.example.com"
```

--------------------------------

### Associate a tenant with the node

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Links a specific tenant, identified by its tenant ID, to the current node configuration. This operation loads the tenant's details from an environment file.

```shell
twin-node node-set-tenant --load-env="node-tenant.env" --tenant-id=!NODE_TENANT_ID
```

--------------------------------

### Create User Login for Organization User

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Establishes a user login associated with a previously created user identity and organization. It requires multiple environment files for context and outputs user account details in JSON and environment files with a specified prefix.

```shell
twin-node user-create --load-env="organization-identity.env,user-identity.env,node-tenant.env" --user-identity=!USER_DID --organization-identity=!ORGANIZATION_DID --tenant-id=!NODE_TENANT_ID --email="admin@node" --output-json="user-account-admin.json" --output-env="user-account-admin.env" --output-env-prefix=admin
```

--------------------------------

### handleNpmProtocol()

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/docs/reference/functions/handleNpmProtocol.md

Handles the npm protocol by installing the specified package if it's not already present. This function is crucial for managing external npm dependencies within the project.

```APIDOC
## POST /twinfoundation/node/handleNpmProtocol

### Description
Handles the npm: protocol by installing the package if needed. This function resolves npm package dependencies by ensuring they are installed and available in the specified cache directory.

### Method
POST

### Endpoint
/twinfoundation/node/handleNpmProtocol

### Parameters
#### Request Body
- **packageName** (string) - Required - The npm package name (without npm: prefix).
- **executionDirectory** (string) - Required - The execution directory.
- **cacheDirectory** (string) - Optional - The cache directory base path.

### Request Example
```json
{
  "packageName": "example-package",
  "executionDirectory": "/path/to/execution",
  "cacheDirectory": "/path/to/cache"
}
```

### Response
#### Success Response (200)
- **resolvedPath** (string) - The resolved path to the installed module.

#### Response Example
```json
{
  "resolvedPath": "/path/to/node_modules/example-package"
}
```
```

--------------------------------

### Display help for a specific twin-node command

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Retrieves detailed help information for a particular twin-node command, including its specific options and arguments. This is helpful for learning how to use individual commands.

```shell
twin-node command --help
```

--------------------------------

### Install TWIN Node Core with npm

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/README.md

This snippet shows how to install the TWIN Node Core package using npm. It is a prerequisite for using the core components in your project.

```shell
npm install @twin.org/node-core
```

--------------------------------

### Deploy TWIN Node using Docker (Bash and YAML)

Source: https://context7.com/twinfoundation/node/llms.txt

Instructions for deploying TWIN Node using Docker. This includes building the Docker image and running the container with persistent storage configurations, as well as a Docker Compose example.

```bash
# Build Docker image
docker build -t twin-node -f deploy/dockerfile . --load

# Run with persistent storage
docker run -t -i \
  -v /home/twin-node/data:/twin-node/data \
  -p 3000:3000 \
  twin-node
```

```yaml
# docker-compose.yml
version: '3.8'
services:
  twin-node:
    build:
      context: .
      dockerfile: deploy/dockerfile
    ports:
      - "3000:3000"
    volumes:
      - twin-data:/twin-node/data
    environment:
      - TWIN_HOST=0.0.0.0
      - TWIN_PORT=3000
      - TWIN_STORAGE_FILE_ROOT=/twin-node/data
      - TWIN_DEBUG=true

volumes:
  twin-data:
```

--------------------------------

### Bootstrap twin-node in legacy mode

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Initializes the twin-node in a legacy mode, potentially loading environment variables from a specified file. Note that this mode is marked for deprecation in future versions.

```shell
twin-node bootstrap-legacy --load-env=".env.bootstrap-legacy"
```

--------------------------------

### Import an existing vault key for authentication signing

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Imports a pre-existing cryptographic key for node authentication signing. This command loads necessary details from specified files and requires the node's identity DID and key ID.

```shell
twin-node vault-key-import --load-env="node-identity.env,my-key.json" --identity=!NODE_DID --key-id=!TWIN_AUTH_SIGNING_KEY_ID --key-type=!KEY_TYPE --private-key-hex=!PRIVATE_KEY_HEX
```

--------------------------------

### Import an existing node identity

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Imports an existing decentralized identity for the node using details loaded from an environment file. Requires specifying the identity DID and mnemonic phrase.

```shell
twin-node identity-import --load-env="my-identity.env" --identity=!MY_DID --mnemonic=!MY_MNEMONIC
```

--------------------------------

### Import an existing verification method for organization identity attestation

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Imports a pre-existing verification method for an organization's identity attestation. This command loads necessary details from multiple files and requires the organization's identity DID, controller DID, and verification method ID.

```shell
twin-node identity-verification-method-import --load-env="node-identity.env,organization-identity.env,organization-attestation.env" --identity=!ORGANIZATION_DID --controller=!NODE_DID --verification-method-id=!DID_VERIFICATION_METHOD_ID --private-key-hex=!DID_VERIFICATION_METHOD_PRIVATE_KEY_HEX
```

--------------------------------

### Import an existing vault key for node authentication

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Imports an existing cryptographic key for node authentication signing. It requires loading environment and/or JSON files containing the key details, along with the identity DID and key ID.

```shell
twin-node vault-key-import --load-env="node-identity.env,node-auth-key.json" --identity=!NODE_DID --key-id=!TWIN_AUTH_SIGNING_KEY_ID --key-type=!KEY_TYPE --private-key-hex=!PRIVATE_KEY_HEX
```

--------------------------------

### Bootstrap and Run Twin Foundation Node Server

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/deployment-ec2.md

Initializes and runs the Twin Foundation Node server. This command starts the server, initializes services, and generates configuration files. It's important to note the initial logging output for admin passwords.

```shell
node ./dist/es/index.js
```

--------------------------------

### Associate an identity with the node

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Links a previously created or imported identity (specified by its DID) to the current node configuration. It loads the node's identity details from an environment file.

```shell
twin-node node-set-identity --load-env="node-identity.env" --identity=!NODE_DID
```

--------------------------------

### Example TWIN Node Extension Lifecycle Hooks (JavaScript)

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/docs/detailed-guide.md

Demonstrates how to implement lifecycle hooks within a TWIN Node extension. These hooks allow customization of the node's behavior during initialization and shutdown phases.

```javascript
// my-extension.mjs
export function extensionInitialise() {
  console.log('Extension initializing...');
}

export function extensionInitialiseEngine(engine) {
  console.log('Configuring engine...');
  // Add custom components, routes, etc.
}

export function extensionInitialiseEngineServer(server) {
  console.log('Configuring server...');
  // Add middleware, routes, etc.
}

export function extensionShutdown() {
  console.log('Extension shutting down...');
  // Cleanup resources
}
```

--------------------------------

### Create a verifiable credential for organization attestation

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Generates a verifiable credential based on the organization's attestation verification method. This command requires loading organization identity and attestation details, specifying the organization's DID, the verification method ID, and subject information in a JSON file.

```shell
twin-node identity-verifiable-credential-create --load-env="organization-identity.env,organization-attestation.env" --identity=!ORGANIZATION_DID --verification-method-id=!TWIN_ATTESTATION_VERIFICATION_METHOD_ID --subject-json="subject.json" --output-json="organization-attestation-credential.json" --output-env="organization-attestation-credential.env"
```

--------------------------------

### Create Organization Verification Method for Trust

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Creates a verification method for an organization's identity to establish trust. It requires environment variables for identity and controller details, and outputs JSON and environment files for configuration.

```shell
twin-node identity-verification-method-create --load-env="node-identity.env,organization-identity.env" --identity=!ORGANIZATION_DID --controller=!NODE_DID --verification-method-id=!TWIN_TRUST_VERIFICATION_METHOD_ID --output-json="organization-trust.json" --output-env="organization-trust.env"
```

--------------------------------

### Run Custom TWIN Node Programmatically (TypeScript)

Source: https://context7.com/twinfoundation/node/llms.txt

This snippet demonstrates how to programmatically start a custom TWIN Node using the node-core package. It includes overriding module imports, building configuration from environment variables, and extending configuration with custom logic. Dependencies include '@twin.org/node-core'.

```typescript
import {
  run,
  buildConfiguration,
  buildEngineConfiguration,
  buildEngineServerConfiguration,
  overrideModuleImport,
  parseModuleProtocol,
  handleNpmProtocol,
  handleHttpsProtocol
} from '@twin.org/node-core';

// Custom node implementation
async function startCustomNode() {
  // Override module imports for extension loading
  overrideModuleImport(process.cwd());

  // Build configuration from environment
  const processEnv = {
    TWIN_HOST: "0.0.0.0",
    TWIN_PORT: "3000",
    TWIN_DEBUG: "true"
  };

  const options = {
    envPrefix: "TWIN_",
    executionDirectory: process.cwd(),
    extendEnvVars: async (envVars) => {
      // Add custom environment variables
      envVars.customVar = "customValue";
    },
    extendConfig: async (envVars, config) => {
      // Modify configuration before startup
      config.customComponent = { enabled: true };
    }
  };

  const serverInfo = { name: "Custom TWIN Node", version: "1.0.0" };

  const { nodeEngineConfig, nodeEnvVars } = 
    await buildConfiguration(processEnv, options, serverInfo);

  // Start the node
  const result = await run(options, process.argv);

  return result;
}

startCustomNode().catch(console.error);
```

--------------------------------

### Create a verification method for organization identity immutable proofs

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Adds a new verification method to an organization's identity, specifically for use in creating immutable proofs. It requires loading node and organization identity details, specifying the identity DID, controller DID, and a unique verification method ID.

```shell
twin-node identity-verification-method-create --load-env="node-identity.env,organization-identity.env" --identity=!ORGANIZATION_DID --controller=!NODE_DID --verification-method-id=!TWIN_IMMUTABLE_PROOF_VERIFICATION_METHOD_ID --output-json="organization-immutable-proof.json" --output-env="organization-immutable-proof.env"
```

--------------------------------

### Create a new vault key for node authentication

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/examples.md

Generates a new cryptographic key to be used for authentication signing by the node. The key details can be output to JSON and environment files, and it requires the node's identity and a key ID.

```shell
twin-node vault-key-create --load-env="node-identity.env" --identity=!NODE_DID --key-id=!TWIN_AUTH_SIGNING_KEY_ID --output-json="node-auth-key.json" --output-env="node-auth-key.env"
```

--------------------------------

### extensionsInitialiseEngineServer()

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/docs/reference/functions/extensionsInitialiseEngineServer.md

Initializes extensions for the engine server.

```APIDOC
## extensionsInitialiseEngineServer()

### Description
Handles the initialisation of the extensions when the engine server has been constructed.

### Method
`Promise<void>`

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
// Example usage within a Node.js environment
// Assuming envVars, engineCore, and engineServer are already defined
// extensionsInitialiseEngineServer(envVars, engineCore, engineServer);
```

### Response
#### Success Response (void)
This function does not return any value upon successful execution.

#### Response Example
None
```

--------------------------------

### Install Nginx on EC2 Instance

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/deployment-ec2.md

Installs Nginx, a web server and reverse proxy, on an EC2 instance using `yum`. Nginx is used to serve the Node.js application over HTTPS. The installation is verified by printing the Nginx version.

```shell
sudo yum install nginx -y
nginx -v
```

--------------------------------

### Build Engine Server Configuration

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/docs/reference/functions/buildEngineServerConfiguration.md

Handles the configuration of the server by taking environment variables, context keys, core engine configuration, server information, and optional paths for OpenAPI specification and favicon.

```APIDOC
## Function: buildEngineServerConfiguration()

### Description
Handles the configuration of the server. This function takes various configuration objects and optional paths to set up the engine server.

### Method
`buildEngineServerConfiguration`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
*   **envVars** (`IEngineServerEnvironmentVariables`) - Required - The environment variables for the engine server.
*   **availableContextIdKeys** (`object`[]) - Required - The context ID keys.
*   **coreEngineConfig** (`IEngineCoreConfig`) - Required - The core engine config.
*   **serverInfo** (`IServerInfo`) - Required - The server information.
*   **openApiSpecPath** (`string`) - Optional - The path to the open api spec.
*   **favIconPath** (`string`) - Optional - The path to the favicon.

### Request Example
```javascript
// Example usage (assuming necessary imports and variables are defined)
const config = await buildEngineServerConfiguration(
  envVars,
  availableContextIdKeys,
  coreEngineConfig,
  serverInfo,
  "/path/to/openapi.yaml",
  "/path/to/favicon.ico"
);
```

### Response
#### Success Response (Promise<IEngineServerConfig>)
*   **Returns** (`Promise<IEngineServerConfig>`) - The config for the core and the server.

#### Response Example
```json
{
  "coreConfig": { ... },
  "serverConfig": { ... }
}
```
```

--------------------------------

### Install NVM and Node.js on EC2 Instance

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/deployment-ec2.md

Installs Node Version Manager (NVM) and Node.js version 20 on an EC2 instance. NVM is used to manage multiple Node.js versions, and Node.js is required to build and run the application. The installation script is downloaded via `curl`, and the Node.js version is verified.

```shell
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
node -v
```

--------------------------------

### Blob Storage API: Manage Binary Data

Source: https://context7.com/twinfoundation/node/llms.txt

Provides functionality to store and retrieve binary data using base64 encoding. Supports creating, getting metadata, getting content, and deleting blobs.

```bash
# Create a blob (base64 encoded content)
curl -X POST http://localhost:3000/blob-storage \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "blob": "SGVsbG8gV29ybGQh"
  }'

# Get blob metadata
curl -X GET "http://localhost:3000/blob-storage/blob:0x1234567890abcdef..." \
  -H "Cookie: access_token=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."

# Get blob content
curl -X GET "http://localhost:3000/blob-storage/blob:0x1234567890abcdef.../content" \
  -H "Cookie: access_token=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."

# Delete blob
curl -X DELETE "http://localhost:3000/blob-storage/blob:0x1234567890abcdef..." \
  -H "Cookie: access_token=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Configure TWIN Node Server via Environment Variables

Source: https://context7.com/twinfoundation/node/llms.txt

Demonstrates how to configure the TWIN Node server using environment variables, including basic settings, extension loading from various sources, and cache configuration.

```bash
# Basic server configuration (.env file)
TWIN_HOST=0.0.0.0
TWIN_PORT=3000
TWIN_STORAGE_FILE_ROOT=/twin-node/data
TWIN_DEBUG=true

# Extension loading from multiple sources
TWIN_EXTENSIONS="./my-extension.mjs"
TWIN_EXTENSIONS="npm:@twin.org/identity-management-service"
TWIN_EXTENSIONS="https://example.twin.org/extensions/my-module.mjs"

# Multiple extensions (comma-separated)
TWIN_EXTENSIONS="npm:@twin.org/custom-service,./local-extension.mjs"

# Extension cache configuration
TWIN_EXTENSIONS_MAX_SIZE_MB=10
TWIN_EXTENSIONS_CACHE_DIRECTORY=".tmp"
TWIN_EXTENSIONS_CLEAR_CACHE=false
```

--------------------------------

### GET /authentication/logout

Source: https://context7.com/twinfoundation/node/llms.txt

Logs out the current user by invalidating the authentication token.

```APIDOC
## GET /authentication/logout

### Description
Logs out the user.

### Method
GET

### Endpoint
`/authentication/logout`

### Parameters
#### Headers
- **Cookie** (string) - Required - The access token cookie. Example: `access_token=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...`

### Request Example
```bash
curl -X GET "http://localhost:3000/authentication/logout" \
  -H "Cookie: access_token=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
```

### Response
#### Success Response (200)
This endpoint typically returns a success status code (e.g., 200 OK) upon successful logout, often with an empty response body or a confirmation message.
```

--------------------------------

### ScyllaDB Configuration

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/docs/reference/interfaces/IEngineServerEnvironmentVariables.md

Environment variables for configuring ScyllaDB connection.

```APIDOC
## ScyllaDB Configuration

### Description
Configure connection details for ScyllaDB.

### Method
N/A (Environment Variables)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **scylladbHosts** (string) - Optional - ScyllaDB hosts as comma separated string.
- **scylladbKeyspace** (string) - Optional - ScyllaDB keyspace.
- **scylladbLocalDataCenter** (string) - Optional - ScyllaDB local data center.
- **scylladbPort** (string) - Optional - ScyllaDB port.

### Request Example
```json
{
  "scylladbHosts": "192.168.1.1,192.168.1.2",
  "scylladbKeyspace": "my_keyspace",
  "scylladbLocalDataCenter": "datacenter1",
  "scylladbPort": "9042"
}
```

### Response
#### Success Response (N/A)
N/A

#### Response Example
N/A
```

--------------------------------

### Get NFT

Source: https://context7.com/twinfoundation/node/llms.txt

Retrieves an NFT by its unique ID. Requires a valid access token.

```bash
curl -X GET "http://localhost:3000/nft/{nftId}" \
  -H "Cookie: access_token=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Extension API: extensionInitialiseEngineServer

Source: https://github.com/twinfoundation/node/blob/next/apps/node/docs/configuration.md

The `extensionInitialiseEngineServer` function is called after the engine server is created but before it begins listening. This is suitable for adding routes or configuring the server.

```typescript
export async function extensionInitialiseEngineServer(
  engineCore: IEngineCore,
  engineServer: IEngineServer
): Promise<void> {
  // Add routes, configure server, etc.
}
```

--------------------------------

### GET /authentication/refresh

Source: https://context7.com/twinfoundation/node/llms.txt

Refreshes the authentication token, providing a new token with an updated expiration time.

```APIDOC
## GET /authentication/refresh

### Description
Refresh authentication tokens.

### Method
GET

### Endpoint
`/authentication/refresh`

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication. Example: `Bearer <your_token>`

### Request Example
```bash
curl -X GET "http://localhost:3000/authentication/refresh" \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
```

### Response
#### Success Response (200)
- **expiry** (number) - The expiration timestamp of the refreshed access token.

#### Response Example
```json
{
  "expiry": 1722514341067
}
```
```

--------------------------------

### Initialize Locales

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/docs/reference/functions/initialiseLocales.md

Initializes the application's locales by specifying the directory where locale files are stored. This function returns a Promise that resolves when the initialization is complete.

```APIDOC
## POST /twinfoundation/node/initialiseLocales

### Description
Initialise the locales for the application.

### Method
POST

### Endpoint
/twinfoundation/node/initialiseLocales

### Parameters
#### Query Parameters
- **localesDirectory** (string) - Required - The directory containing the locales.

### Request Example
```json
{
  "localesDirectory": "./path/to/locales"
}
```

### Response
#### Success Response (200)
- **void** - The promise resolves with no specific value upon successful initialization.

#### Response Example
```json
// No response body for success, promise resolves.
```
```

--------------------------------

### Get Environment Defaults

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/docs/reference/functions/getEnvDefaults.md

Retrieves the default environment variables for the Node.js application, optionally filtered by an environment variable prefix.

```APIDOC
## GET /env/defaults

### Description
Retrieves the default environment variables for the Node.js application. You can provide an environment variable prefix to filter the results.

### Method
GET

### Endpoint
/env/defaults

### Parameters
#### Query Parameters
- **envPrefix** (string) - Optional - The environment variable prefix to filter the default environment variables.

### Request Example
```
GET /env/defaults?envPrefix=APP_
```

### Response
#### Success Response (200)
- **object** (object) - An object containing the default environment variables.

#### Response Example
```json
{
  "NODE_ENV": "development",
  "PORT": "3000",
  "APP_LOG_LEVEL": "info"
}
```
```

--------------------------------

### Get Server Info

Source: https://context7.com/twinfoundation/node/llms.txt

Retrieves general information about the TWIN Node server, including its name and version.

```bash
curl http://localhost:3000/info
```

--------------------------------

### Get Attestation

Source: https://context7.com/twinfoundation/node/llms.txt

Retrieves an existing attestation using its unique ID. Requires a valid access token.

```bash
curl -X GET "http://localhost:3000/attestation/{attestationId}" \
  -H "Cookie: access_token=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Get OpenAPI Specification

Source: https://context7.com/twinfoundation/node/llms.txt

Fetches the OpenAPI specification for the TWIN Node API. This is useful for understanding the available endpoints and their structures.

```shell
curl http://localhost:3000/spec
```

--------------------------------

### MySQL Configuration

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/docs/reference/interfaces/IEngineServerEnvironmentVariables.md

Environment variables for configuring MySQL connection.

```APIDOC
## MySQL Configuration

### Description
Configure connection details for MySQL database.

### Method
N/A (Environment Variables)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **mySqlHost** (string) - Optional - MySQL host.
- **mySqlPort** (number) - Optional - MySQL port.
- **mySqlUser** (string) - Optional - MySQL username.
- **mySqlPassword** (string) - Optional - MySQL password.
- **mySqlDatabase** (string) - Optional - MySQL Database.

### Request Example
```json
{
  "mySqlHost": "localhost",
  "mySqlPort": 3306,
  "mySqlUser": "admin",
  "mySqlPassword": "password",
  "mySqlDatabase": "mydatabase"
}
```

### Response
#### Success Response (N/A)
N/A

#### Response Example
N/A
```

--------------------------------

### Node Configuration Environment Variables

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/docs/reference/interfaces/INodeEnvironmentVariables.md

This section details the optional environment variables that can be used to configure the node's behavior, including various connectors, IOTA network parameters, and identity-related settings.

```APIDOC
## Node Configuration Environment Variables

### Description
This section details the optional environment variables that can be used to configure the node's behavior, including various connectors, IOTA network parameters, and identity-related settings.

### Parameters
#### Query Parameters

- **faucetConnector** (string) - Optional - The type of faucet connector: entity-storage, iota.
- **walletConnector** (string) - Optional - The type of wallet connector: entity-storage, iota.
- **nftConnector** (string) - Optional - The type of NFT connector: entity-storage, iota.
- **identityConnector** (string) - Optional - The type of identity connector: entity-storage, iota.
- **identityWalletAddressIndex** (string) - Optional - The index of the wallet address to use, defaults to 0.
- **identityResolverConnector** (string) - Optional - The type of identity resolver connector: entity-storage, iota.
- **verifiableStorageConnector** (string) - Optional - The type of verifiable storage connector: entity-storage, iota.
- **iotaFaucetEndpoint** (string) - Optional - IOTA Faucet Endpoint.
- **iotaNodeEndpoint** (string) - Optional - IOTA Node Endpoint.
- **iotaNetwork** (string) - Optional - IOTA network.
- **iotaCoinType** (string) - Optional - IOTA coin type.
- **iotaExplorerEndpoint** (string) - Optional - IOTA Explorer Endpoint.
- **iotaGasStationEndpoint** (string) - Optional - IOTA Gas Station Endpoint.
- **iotaGasStationAuthToken** (string) - Optional - IOTA Gas Station Authentication Token.
- **universalResolverEndpoint** (string) - Optional - Universal Resolver Endpoint.
- **identityProfileConnector** (string) - Optional - The type of identity profile connector: entity-storage.
- **immutableProofVerificationMethodId** (string) - Optional - The identity verification method id to use with immutable proofs.

### Request Example
```json
{
  "faucetConnector": "iota",
  "iotaNodeEndpoint": "https://api.testnet.iota.org",
  "identityConnector": "entity-storage"
}
```

### Response
#### Success Response (200)
This endpoint does not return a specific success response body as it configures the node's environment variables.

#### Response Example
N/A
```

--------------------------------

### Get Auditable Item Graph Vertex

Source: https://context7.com/twinfoundation/node/llms.txt

Retrieves an auditable item graph vertex by its ID. Requires a valid access token.

```bash
curl -X GET "http://localhost:3000/aig/{vertexId}" \
  -H "Cookie: access_token=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Get Specific Telemetry Metric

Source: https://context7.com/twinfoundation/node/llms.txt

Retrieves details for a specific telemetry metric using its ID. Requires a valid access token.

```bash
curl -X GET "http://localhost:3000/telemetry/metric/my-counter" \
  -H "Cookie: access_token=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### PostgreSQL Configuration

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/docs/reference/interfaces/INodeEnvironmentVariables.md

Environment variables for configuring the PostgreSQL connection.

```APIDOC
## PostgreSQL Configuration

### Description
Environment variables for configuring the PostgreSQL connection.

### Method
N/A (Environment Variables)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **postgreSqlHost** (string) - Optional - PostgreSQL host.
- **postgreSqlPort** (number) - Optional - PostgreSQL port.
- **postgreSqlUser** (string) - Optional - PostgreSQL username.
- **postgreSqlPassword** (string) - Optional - PostgreSQL password.
- **postgreSqlDatabase** (string) - Optional - PostgreSQL Database.

### Request Example
```json
{
  "postgreSqlHost": "localhost",
  "postgreSqlPort": 5432,
  "postgreSqlUser": "admin",
  "postgreSqlPassword": "password",
  "postgreSqlDatabase": "mydatabase"
}
```

### Response
#### Success Response (N/A)
N/A

#### Response Example
N/A
```

--------------------------------

### Get Auditable Item Graph Vertex as JSON-LD

Source: https://context7.com/twinfoundation/node/llms.txt

Retrieves an auditable item graph vertex formatted as JSON-LD. Requires the vertex ID and a valid access token.

```bash
curl -X GET "http://localhost:3000/aig/{vertexId}/json-ld" \
  -H "Cookie: access_token=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Load Extensions from NPM Packages

Source: https://github.com/twinfoundation/node/blob/next/packages/node-core/docs/detailed-guide.md

Automatically installs and loads extensions from NPM packages by prefixing the package name with 'npm:'. The TWIN Node handles the dependency management.

```bash
TWIN_EXTENSIONS="npm:@twin.org/package"
```