# @flink-app/management-actions-plugin

> Flink plugin that makes it possible create actions that can be run trought the management-api

Latest version **1.0.0** (published 2026-02-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @flink-app/management-actions-plugin
pnpm add @flink-app/management-actions-plugin
yarn add @flink-app/management-actions-plugin
bun add @flink-app/management-actions-plugin
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2026-02-01 |
| First published | 2022-01-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 46.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | johan@frost.se |
| Maintainers | joelso, jenkins-frost, johanfrost |

## Links

- npm: https://www.npmjs.com/package/@flink-app/management-actions-plugin
- npm.io page: https://npm.io/package/@flink-app/management-actions-plugin

## Dependencies (3)

- [node-color-log](https://npm.io/package/node-color-log.md) ^5.3.1
- [@flink-app/flink](https://npm.io/package/@flink-app/flink.md) 1.0.0
- [@flink-app/management-api-plugin](https://npm.io/package/@flink-app/management-api-plugin.md) 1.0.0

## Recent versions

- 1.0.0 (latest) — 2026-02-01
- 2.0.0-alpha.134 (alpha) — 2026-11-07
- 2.0.0-alpha.133 — 2026-11-06
- 2.0.0-alpha.132 — 2026-11-05
- 2.0.0-alpha.131 — 2026-10-28
- 2.0.0-alpha.130 — 2026-10-25
- 2.0.0-alpha.129 — 2026-10-25
- 2.0.0-alpha.128 — 2026-10-22
- 2.0.0-alpha.127 — 2026-10-18
- 2.0.0-alpha.126 — 2026-10-18
- 2.0.0-alpha.125 — 2026-10-17
- 2.0.0-alpha.124 — 2026-10-16
- 2.0.0-alpha.123 — 2026-09-30
- 2.0.0-alpha.122 — 2026-09-28
- 2.0.0-alpha.121 — 2026-09-19
- … 130 more at https://npm.io/package/@flink-app/management-actions-plugin/versions

## README

# @flink-app/management-actions-plugin

A Flink management API module that enables you to create and execute custom actions through the management API. This plugin integrates with `@flink-app/management-api-plugin` to expose server-side actions that can be triggered via HTTP requests.

## Features

- Define custom server-side actions with arguments
- Execute actions through the management API
- Type-safe argument handling
- Built-in UI support for management interfaces
- Flexible response handling with success/error states
- List all available actions via API

## Prerequisites

This plugin requires `@flink-app/management-api-plugin` to be installed and configured in your Flink application.

```bash
npm install @flink-app/management-api-plugin
```

## Installation

```bash
npm install @flink-app/management-actions-plugin
```

## Usage

### Basic Setup

```typescript
import { FlinkApp } from "@flink-app/flink";
import { managementApiPlugin } from "@flink-app/management-api-plugin";
import {
  GetManagementModule,
  ActionArugmentType,
  ActionReturnStatus,
} from "@flink-app/management-actions-plugin";

const actionsModule = GetManagementModule({
  ui: true,
  uiSettings: {
    title: "Actions",
  },
  actions: [
    {
      id: "hello-world",
      description: "Greets you with a personalized message",
      arguments: [
        {
          id: "name",
          type: ActionArugmentType.text,
          required: true,
        },
      ],
      async handler(ctx, args) {
        return {
          data: {
            message: "Hello " + args.name,
          },
          status: ActionReturnStatus.success,
        };
      },
    },
  ],
});

function start() {
  new FlinkApp<AppContext>({
    name: "My app",
    plugins: [
      managementApiPlugin({
        token: "SECRET_TOKEN",
        jwtSecret: "JWT_SECRET",
        modules: [actionsModule],
      }),
    ],
  }).start();
}
```

## Action Definition

Each action requires the following properties:

### Action Interface

```typescript
interface Action {
  id: string; // Unique identifier for the action
  description?: string; // Human-readable description
  arguments: ActionArguments[]; // Array of input arguments
  handler: (ctx: FlinkContext<any>, args: ActionArgumentsValues) => Promise<ActionResponse>;
}
```

### Action Arguments

```typescript
interface ActionArguments {
  id: string; // Argument identifier
  required: boolean; // Whether the argument is required
  type: ActionArugmentType; // Argument type
  default?: string; // Optional default value
}

enum ActionArugmentType {
  text = "TEXT",
}
```

### Action Response

```typescript
interface ActionResponse {
  status: ActionReturnStatus; // SUCCESS or ERROR
  error?: string; // Error message (if status is ERROR)
  data?: {
    [key: string]: any; // Response data (if status is SUCCESS)
  };
}

enum ActionReturnStatus {
  success = "SUCCESS",
  error = "ERROR",
}
```

## API Endpoints

The plugin exposes two endpoints for each actions module:

### List Actions

```
GET /managementapi/{pluginId}
```

Returns a list of all available actions with their configurations.

**Response:**
```json
[
  {
    "id": "hello-world",
    "description": "Greets you with a personalized message",
    "arguments": [
      {
        "id": "name",
        "type": "TEXT",
        "required": true
      }
    ]
  }
]
```

### Execute Action

```
POST /managementapi/{pluginId}/{actionId}
```

Executes a specific action with provided arguments.

**Headers:**
```
management-token: YOUR_TOKEN_OR_JWT
```

**Request Body:**
```json
{
  "name": "World"
}
```

**Response:**
```json
{
  "status": "SUCCESS",
  "data": {
    "message": "Hello World"
  }
}
```

## Advanced Examples

### Action with Multiple Arguments

```typescript
{
  id: "create-user",
  description: "Creates a new user in the system",
  arguments: [
    {
      id: "username",
      type: ActionArugmentType.text,
      required: true,
    },
    {
      id: "email",
      type: ActionArugmentType.text,
      required: true,
    },
    {
      id: "role",
      type: ActionArugmentType.text,
      required: false,
      default: "user",
    },
  ],
  async handler(ctx, args) {
    try {
      const user = await ctx.repos.userRepo.create({
        username: args.username,
        email: args.email,
        role: args.role,
      });

      return {
        status: ActionReturnStatus.success,
        data: { userId: user._id },
      };
    } catch (error) {
      return {
        status: ActionReturnStatus.error,
        error: error.message,
      };
    }
  },
}
```

### Action with Database Access

```typescript
{
  id: "cleanup-old-records",
  description: "Removes records older than 30 days",
  arguments: [],
  async handler(ctx, args) {
    try {
      const cutoffDate = new Date();
      cutoffDate.setDate(cutoffDate.getDate() - 30);

      const result = await ctx.repos.recordRepo.deleteMany({
        createdAt: { $lt: cutoffDate },
      });

      return {
        status: ActionReturnStatus.success,
        data: {
          deletedCount: result.deletedCount,
          message: `Removed ${result.deletedCount} old records`,
        },
      };
    } catch (error) {
      return {
        status: ActionReturnStatus.error,
        error: `Failed to cleanup records: ${error.message}`,
      };
    }
  },
}
```

### Action with External API Call

```typescript
{
  id: "sync-data",
  description: "Syncs data from external service",
  arguments: [
    {
      id: "service",
      type: ActionArugmentType.text,
      required: true,
    },
  ],
  async handler(ctx, args) {
    try {
      const response = await fetch(`https://api.example.com/${args.service}`);
      const data = await response.json();

      // Process and store data
      await ctx.repos.dataRepo.create(data);

      return {
        status: ActionReturnStatus.success,
        data: {
          recordsImported: data.length,
          service: args.service,
        },
      };
    } catch (error) {
      return {
        status: ActionReturnStatus.error,
        error: `Sync failed: ${error.message}`,
      };
    }
  },
}
```

## Configuration Options

### GetManagementModule Options

```typescript
interface GetManagementModuleConfig {
  pluginId?: string; // Custom plugin ID (defaults to "managementActionsApi")
  ui: boolean; // Enable UI features
  uiSettings?: {
    title: string; // Display title in management UI
  };
  actions: Action[]; // Array of actions to register
}
```

## Context Access

Action handlers receive the full Flink context, providing access to:

- `ctx.repos` - All registered repositories
- `ctx.db` - MongoDB database connection
- `ctx.plugins` - All plugin contexts
- Any other context properties from your application

## Security

All action endpoints are protected by the management API authentication system. Ensure you:

- Use the management token header for all requests
- Validate and sanitize action arguments
- Implement proper error handling
- Avoid exposing sensitive data in responses
- Log action executions for audit purposes

## Testing Actions

You can test your actions using curl or any HTTP client:

```bash
# Get list of actions
curl 'https://your-api.com/managementapi/managementActionsApi' \
  -H 'management-token: YOUR_TOKEN'

# Execute an action
curl -X POST 'https://your-api.com/managementapi/managementActionsApi/hello-world' \
  -H 'management-token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"World"}'
```

## TypeScript Support

The plugin is written in TypeScript and provides full type definitions for all interfaces and enums.

## Error Handling

Always return proper error responses from action handlers:

```typescript
async handler(ctx, args) {
  try {
    // Your action logic
    return {
      status: ActionReturnStatus.success,
      data: { /* your data */ },
    };
  } catch (error) {
    return {
      status: ActionReturnStatus.error,
      error: error instanceof Error ? error.message : "Unknown error",
    };
  }
}
```

## License

MIT

---
_Source: https://npm.io/package/@flink-app/management-actions-plugin · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
