@datanimbus/dnio-mcp 1.0.0

package/docs/tools/records.md

@@ -0,0 +1,97 @@
+# Records (CRUD)
+
+Two layers of tools for working with the records inside data services:
+
+- **Static, generic** — registered by `src/tools/records.js`. Take a `serviceName` arg and resolve it via the registry.
+- **Dynamic, typed** — registered per-service by `src/tools/data-service-registry.js` after `select_app` succeeds. Each service gets six tools named `<toolPrefix>_list/_get/_create/_update/_delete/_count` with input schemas converted from the service's `definition`.
+
+Both layers hit the same backing endpoints via `RecordsClient` (`src/clients/records.js`). All require an app to be selected first.
+
+Endpoint pattern: `/api/c/${app}/${servicePath}[/${recordId}][/utils/count]`.
+
+## Static, generic tools (`src/tools/records.js`)
+
+### `list_records`
+
+| | |
+|---|---|
+| **Purpose** | List/search records, with MongoDB-style filter, sort, select, pagination. |
+| **Inputs** | `serviceName` (required), `filter` (string, JSON), `sort` (string, prefix `-` for desc), `select` (CSV), `page` (int, default 1), `count` (int 1–100, default 20). |
+| **Endpoint** | `GET /api/c/${app}/${servicePath}?filter=…&sort=…&select=…&page=…&count=…` |
+| **Returns** | `{ service, count, page, records }` |
+
+### `get_record`
+
+| | |
+|---|---|
+| **Purpose** | Fetch a single record by ID. |
+| **Inputs** | `serviceName` (required), `recordId` (required), `expand` (boolean, default false). |
+| **Endpoint** | `GET /api/c/${app}/${servicePath}/${recordId}[?expand=true]` |
+| **Returns** | `{ service, record }`. 404 from the platform is converted to a friendly "not found" message instead of an error. |
+
+### `create_record`
+
+| | |
+|---|---|
+| **Purpose** | Create a record. Use `get_service_schema` first if you don't already know the field shape. |
+| **Inputs** | `serviceName` (required), `data` (required, JSON string). |
+| **Endpoint** | `POST /api/c/${app}/${servicePath}` |
+| **Returns** | `{ service, action: 'created', record }` |
+
+### `update_record`
+
+| | |
+|---|---|
+| **Purpose** | Patch fields on an existing record. Partial updates are supported. |
+| **Inputs** | `serviceName` (required), `recordId` (required), `data` (required, JSON string). |
+| **Endpoint** | `PUT /api/c/${app}/${servicePath}/${recordId}` |
+| **Returns** | `{ service, action: 'updated', recordId, record }` |
+
+### `delete_record`
+
+| | |
+|---|---|
+| **Purpose** | Permanently delete a record. Marked as a destructive tool. |
+| **Inputs** | `serviceName` (required), `recordId` (required). |
+| **Endpoint** | `DELETE /api/c/${app}/${servicePath}/${recordId}` |
+| **Returns** | `{ service, action: 'deleted', recordId, result }` |
+
+### `count_records`
+
+| | |
+|---|---|
+| **Purpose** | Count records, with optional filter. Has a 1-second client timeout because the count endpoint is expected to be fast and is also used for pod liveness checks. |
+| **Inputs** | `serviceName` (required), `filter` (optional JSON string). |
+| **Endpoint** | `GET /api/c/${app}/${servicePath}/utils/count[?filter=…]` |
+| **Returns** | `{ service, count }` |
+
+## Dynamic, typed tools (per-service)
+
+After `select_app` lands, `data-service-registry.js` walks each loaded service and registers six tools using the slugified service name as the prefix:
+
+| Tool | Verb | Notes |
+|---|---|---|
+| `<prefix>_list` | GET | Same args/behaviour as `list_records` but pre-bound to that service. |
+| `<prefix>_get` | GET | Single record by ID. |
+| `<prefix>_create` | POST | `data` argument is a typed object (Zod schema generated from the service's `definition` via `src/schemas/schema-converter.js`). |
+| `<prefix>_update` | PUT | Same as above; partial updates allowed. |
+| `<prefix>_delete` | DELETE | Destructive. |
+| `<prefix>_count` | GET | Optional filter. |
+
+The `toolPrefix` is computed as `name.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '')`. So a service named `userAccount` becomes `useraccount_list`, `useraccount_create`, etc.
+
+The typed `_create` and `_update` tools accept `data` as a real object (matched against the converted Zod schema), unlike the generic tools which accept a JSON string.
+
+## Service resolution
+
+The static tools accept any of these as `serviceName`:
+- The exact `_id` (e.g. `SRVC13120`).
+- The exact name (case-insensitive).
+- The slugified `toolPrefix`.
+
+Resolution lives in `ServiceRegistry.resolveService(identifier)`. If no match, the tool returns an error that includes the available service names.
+
+## Why both layers exist
+
+- The **dynamic** tools are the ergonomic path: typed inputs, no need to remember service names, no JSON-string serialization for create/update.
+- The **static** tools are the fallback: they work even when the agent doesn't yet know the schema, and they're listed in MCP's tool catalog before any app is selected.

package/docs/workflows.md

@@ -0,0 +1,195 @@
+# End-to-End Workflows
+
+Three reference walkthroughs that combine multiple domains. Each describes the tool calls in order — what the agent runs, in what sequence — and what gets auto-injected by the server.
+
+## 1. Create a data service from scratch
+
+Goal: define a new `student-record` data service in app `dx-mcp` and deploy it.
+
+```
+list_apps                                  # discover apps
+select_app(appName: 'dx-mcp')              # required first
+list_connectors                            # optional: see existing connectors
+                                           # (default DB + STORAGE auto-attached if omitted)
+get_data_service_spec                      # mandatory: read the spec the LLM should follow
+create_data_service(data: '{
+  "name": "student-record",
+  "description": "Stores student records",
+  "definition": [
+    { "key": "_id", "type": "String", "prefix": "STU", "counter": 1001,
+      "properties": {"name":"ID","fieldLength":10,"_typeChanged":"id"} },
+    { "key": "fullName", "type": "String",
+      "properties": {"name":"fullName","required":true,"_typeChanged":"String"} },
+    { "key": "grade", "type": "Number",
+      "properties": {"name":"grade","precision":0,"_typeChanged":"Number"} }
+  ]
+}')
+deploy_data_service(serviceId: 'SRVC<id>')
+refresh_services                           # so the new typed CRUD tools appear
+```
+
+**Auto-injected by `create_data_service`:**
+- `payload.app = registry.selectedApp` — required by the platform.
+- `payload.connectors` — defaults if missing (default DB + default STORAGE).
+- `payload.role` — `{ roles, fields }` with three standard roles (No Access / Manage / View) and a permission map mirroring the `definition`.
+
+After `refresh_services`, six typed tools (`student_record_list`, `student_record_create`, …) appear automatically.
+
+## 2. Build, configure, and publish a flow
+
+Goal: build an HTTP-triggered flow that receives a JSON file, parses it, saves to S3, and returns a response.
+
+```
+list_apps
+select_app(appName: 'dx-mcp')
+
+# Plugin discovery: find or install the trigger
+list_trigger_plugins                                    # check installed
+list_marketplace_plugins(search: 'HTTP')                # if not installed
+install_plugins(marketIds: [<V1_HTTP_SERVER marketId>])
+list_trigger_plugins                                    # confirm + grab full plugin object
+
+# And process plugins
+list_process_plugins(search: 'Parse')                   # → V1_PARSE_JSON
+list_process_plugins(search: 'Save File')               # → V1_SAVE_FILE
+list_process_plugins(search: 'Response')                # → V1_RESPONSE
+
+# Need a connector for V1_SAVE_FILE
+list_connectors(category: 'STORAGE')                    # check existing
+list_connector_types(category: 'STORAGE')               # if creating a new one
+create_connector(name: 'My S3', marketItemId: '<id>',
+                 values: '{"bucket":"…","accessKeyId":"…","secretAccessKey":"…","region":"…"}')
+
+# Create the flow with the trigger
+create_flow(
+  name: 'upload_to_s3',
+  triggerPlugin: <V1_HTTP_SERVER plugin>,
+  triggerOptions: { method: 'POST', path: '/upload' }
+)
+# → returns { flowId: 'FLOW…', status: 'Draft' }
+
+# Wire process nodes
+add_node_to_flow(
+  flowId,
+  pluginObject: <V1_PARSE_JSON plugin>,
+  name: 'parse_body',
+  afterNodeId: 'http_server',
+  mappings: [{ key: 'data', target: {…}, source: [{nodeId:'http_server', dataPath:'data', …}],
+               expression: { type: 'simple', value: "{{http_server['data']}}" } }]
+)
+
+add_node_to_flow(
+  flowId,
+  pluginObject: <V1_SAVE_FILE plugin>,
+  name: 'save_file',
+  afterNodeId: 'parse_body',
+  connector: { _id: 'CON<id>' },
+  mappings: [/* map content from parse_body */]
+)
+
+add_node_to_flow(
+  flowId,
+  pluginObject: <V1_RESPONSE plugin>,
+  name: 'send_response',
+  afterNodeId: 'save_file',
+  mappings: [/* map status, body */]
+)
+
+# Move out of Draft
+publish_flow(flowId)
+
+get_flow(flowId)                          # verify status moved past Draft
+```
+
+### Branching example
+
+To split a path based on whether content is empty:
+
+```
+add_node_to_flow(
+  flowId,
+  pluginObject: <V1_RESPONSE>,
+  name: 'no_content_response',
+  afterNodeId: 'parse_body',
+  branchCondition: { condition: '_.isEmpty({{parse_body["data"]})', name: 'No Content', color: 'FF9800' }
+)
+
+add_node_to_flow(
+  flowId,
+  pluginObject: <V1_SAVE_FILE>,
+  name: 'save_file',
+  afterNodeId: 'parse_body',
+  branchCondition: { condition: '!_.isEmpty({{parse_body["data"]})', name: 'Has Content', color: '4CAF50' }
+)
+```
+
+`parse_body.onSuccess` now has two entries with conditions; the runtime evaluates them and routes accordingly.
+
+### CODEBLOCK fallback
+
+For trivial logic with no first-class plugin, use `V1_CODEBLOCK`:
+
+```
+add_node_to_flow(
+  flowId,
+  pluginObject: <V1_CODEBLOCK plugin>,
+  name: 'enrich_payload',
+  afterNodeId: 'parse_body',
+  options: {
+    code: `async function executeCode(inputData, node, connectorConfig) {
+      try {
+        const enriched = { ...inputData, processedAt: new Date().toISOString() };
+        return { data: enriched };
+      } catch (err) {
+        logger.error(err);
+        throw err;
+      }
+    }`
+  }
+)
+```
+
+The function MUST return `{ data: <whatever> }` — see [`tools/data-pipes.md`](tools/data-pipes.md) for the full contract and runtime globals.
+
+## 3. Deploy a flow to Kubernetes
+
+Goal: take a published flow and turn it into a running K8s deployment.
+
+```
+list_apps
+select_app(appName: 'dx-mcp')
+
+list_available_flows                                            # what's eligible to deploy
+create_deployment_group(name: 'Apple', flowIds: ['FLOW6156'])
+# → { groupId: 'DG2943', status: 'Draft', group: {…} }
+
+start_deployment_group(groupId: 'DG2943')
+# → returns immediately; K8s settles in ~10s
+
+# Verify
+get_deployment_group(groupId: 'DG2943')                         # check status
+get_deployment_group_yamls(groupId: 'DG2943')                   # see generated K8s YAMLs
+
+# Later, after editing + republishing the flow:
+publish_flow(flowId: 'FLOW6156')                                # update the published version
+sync_deployment_group(groupId: 'DG2943')                        # roll forward to the new version
+
+# Tear down (preserving the group):
+stop_deployment_group(groupId: 'DG2943')
+
+# Or delete entirely (frees the bound flows):
+delete_deployment_group(groupId: 'DG2943', confirm: false)      # dry-run: shows what would be freed
+delete_deployment_group(groupId: 'DG2943', confirm: true)       # actually delete
+```
+
+### Rule of thumb: where a flow is
+
+A flow can be in one of three states from the deployment-group perspective:
+
+| State | Visible in | Action |
+|---|---|---|
+| Draft | `list_flows({status:'Draft'})` | Edit further, then `publish_flow`. |
+| Published & not bound to a group | `list_available_flows` | Add to a group via `create_deployment_group` or `add_flows_to_deployment_group`. |
+| Published & bound to a group | `list_deployment_groups` (under `deployments[]`) | Already deployable — `start`/`stop`/`sync`/remove from group. |
+
+If you need to add a flow to a different group, first `remove_flows_from_deployment_group` from its current group — there's no move operation, but remove + add achieves it.

package/env.example

@@ -0,0 +1,16 @@
+# ─── DNIO Admin Credentials (server-side only, used for management APIs) ─────
+DNIO_USERNAME=<DNIO Admin UserNAme>
+DNIO_PASSWORD=<DNIO Admin User Password>
+DNIO_NAMESPACE=<DNIO Namespace>
+DNIO_TOKEN_TTL=1800
+DNIO_BASE_URL="<DNIO Host URL>"
+MCP_USER_EMAIL=<DNIO MCP User ID>
+MCP_USER_PASSWORD=<DNIO MCP User Password>
+
+# ─── MCP Server Settings ─────────────────────────────────────────────────────
+TRANSPORT=http                # 'http' for multi-tenant remote | 'stdio' for local dev
+MCP_PORT=3100                 # HTTP port
+LOG_LEVEL="info"
+
+# ─── Session Settings ────────────────────────────────────────────────────────
+SESSION_TTL=7200              # Session timeout in seconds (default: 2 hours)

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@datanimbus/dnio-mcp",
+  "version": "1.0.0",
+  "description": "MCP Server for DataNimbus BaaS platform - dynamically exposes CRUD tools for all Data Services",
+  "main": "src/index.js",
+  "bin": {
+    "dnio-mcp": "src/index.js"
+  },
+  "files": [
+    "src/",
+    "docs/README.md",
+    "docs/architecture.md",
+    "docs/authentication.md",
+    "docs/workflows.md",
+    "docs/tools/",
+    "readme.md",
+    "env.example",
+    "Dockerfile"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "start:http": "TRANSPORT=http node src/index.js",
+    "start:stdio": "TRANSPORT=stdio node src/index.js",
+    "dev": "nodemon src/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node src/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "express": "^4.21.0",
+    "got": "^11.8.6",
+    "log4js": "^6.9.1",
+    "winston": "^3.17.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/inspector": "0.16.6",
+    "nodemon": "^3.1.0",
+    "dotenv": "^17.3.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,144 @@
+# @datanimbus/dnio-mcp
+
+[![npm version](https://img.shields.io/npm/v/@datanimbus/dnio-mcp.svg)](https://www.npmjs.com/package/@datanimbus/dnio-mcp)
+
+**Model Context Protocol (MCP) server for the [DataNimbus](https://datanimbus.io) BaaS platform.** Exposes Data Services, Connectors, Plugins, Data Pipes (flows), Deployment Groups, and Data Formats as MCP tools — drive the platform from Claude Desktop, Cursor, or any MCP client through natural language.
+
+CRUD tools for every Data Service in the selected app are **registered dynamically** at runtime, so the agent gets typed `list/get/create/update/delete/count` per service the moment you `select_app`.
+
+---
+
+## Prerequisites
+
+- **Node.js ≥ 18** (for native `fetch`).
+- A running **DataNimbus instance** reachable over HTTPS.
+- **Admin credentials** (`DNIO_USERNAME` / `DNIO_PASSWORD`) for management APIs.
+- A pre-provisioned **MCP service account** on the platform (`MCP_USER_EMAIL` / `MCP_USER_PASSWORD`). Server logs in as the service account for data-plane operations and adds it to all apps on first boot. See [`docs/authentication.md`](docs/authentication.md).
+
+---
+
+## Quick Start (Claude Desktop)
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "@datanimbus/dnio-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@datanimbus/dnio-mcp@latest"
+      ],
+      "env": {
+        "DNIO_BASE_URL": "https://your-datanimbus-instance.com",
+        "DNIO_USERNAME": "<admin-username>",
+        "DNIO_PASSWORD": "<admin-password>",
+        "MCP_USER_EMAIL": "<mcp-service-account-email>",
+        "MCP_USER_PASSWORD": "<mcp-service-account-password>",
+        "TRANSPORT": "stdio"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The agent now has access to every DNIO domain tool. Same shape works in Cursor (`.cursor/mcp.json`) or any MCP-compliant client.
+
+For HTTP transport (multi-tenant / remote deployment):
+
+```bash
+TRANSPORT=http MCP_PORT=3100 \
+DNIO_BASE_URL=https://your-datanimbus-instance.com \
+DNIO_USERNAME=<admin-username> \
+DNIO_PASSWORD=<admin-password> \
+MCP_USER_EMAIL=<mcp-service-account-email> \
+MCP_USER_PASSWORD=<mcp-service-account-password> \
+  npx -y @datanimbus/dnio-mcp@latest
+```
+
+Server listens at `http://localhost:3100/mcp` (authless — protect at the network layer).
+
+---
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `DNIO_BASE_URL` | ✅ | — | Platform base URL (e.g. `https://qa.datanimbus.io`). |
+| `DNIO_USERNAME` | ✅ | — | Admin username for management APIs (list apps, fetch schemas, deploy services). |
+| `DNIO_PASSWORD` | ✅ | — | Admin password. |
+| `MCP_USER_EMAIL` | ✅ | — | Service-account email/ID the server logs in as for data-plane operations. |
+| `MCP_USER_PASSWORD` | ✅ | — | Service-account password. |
+| `TRANSPORT` | — | `stdio` | `stdio` for local clients (Claude Desktop / Cursor); `http` for deployed mode. |
+| `MCP_PORT` | — | `3100` | HTTP port (only when `TRANSPORT=http`). |
+| `DNIO_NAMESPACE` | — | `DNIO` | DNIO namespace used for service-account provisioning. |
+| `DNIO_TOKEN_TTL` | — | `1800` | Token TTL in seconds — both admin + MCP-user tokens auto-refresh before expiry. |
+| `LOG_LEVEL` | — | `info` | `debug` / `info` / `warn` / `error`. |
+| `SESSION_TTL` | — | `7200` | HTTP-session lifetime in seconds (HTTP transport only). |
+
+Server fails fast with `[FATAL] Missing required env var: <name>` if any required variable is unset.
+
+**Two-token model:** admin token for management APIs, MCP-user token for data plane. Both managed in memory, never written to disk, never logged. Tool handlers switch tokens explicitly per operation. Full lifecycle in [`docs/authentication.md`](docs/authentication.md).
+
+---
+
+## Available Tools
+
+Tools are organized into product domains. After `select_app`, **per-service typed CRUD tools** are also registered dynamically (`<servicePrefix>_list / _get / _create / _update / _delete / _count`).
+
+### App context
+`list_apps`, `select_app`, `list_services`, `refresh_services`, `get_service_schema`
+
+### Records (CRUD)
+`list_records`, `get_record`, `create_record`, `update_record`, `delete_record`, `count_records` — generic, takes `serviceName` arg. Plus the per-service typed tools mentioned above.
+
+### Data Services (definitions)
+`get_data_service_spec`, `create_data_service`, `get_data_service`, `list_data_services`, `update_data_service`, `deploy_data_service`, `start_stop_data_service`. Auto-injects `app`, default `connectors`, and `role` (3 standard roles + per-field permission map).
+
+### Connectors
+`list_connectors`, `list_connector_types` (marketplace), `create_connector`. Common types: `MONGODB`, `S3`, `SFTP`, `ACTIVEMQ`, `SMTP`.
+
+### Plugins (workflow nodes)
+`list_marketplace_plugins`, `install_plugins`, `list_installed_plugins`, `update_plugins`, `uninstall_plugins`. **Note:** `V1_CODEBLOCK` is a platform built-in — pass directly to flow tools without installing.
+
+### Data Pipes (flows)
+`list_trigger_plugins`, `list_process_plugins`, `list_flows`, `get_flow`, `create_flow`, `add_node_to_flow`, `update_node_in_flow`, `connect_nodes`, `remove_node_from_flow`, `publish_flow`. Auto-maps fields by name match; surfaces unmapped inputs; returns the public invocation URL for HTTP triggers.
+
+### Deployment Groups (Kubernetes)
+`list_available_flows`, `list_deployment_groups`, `get_deployment_group`, `create_deployment_group`, `add_flows_to_deployment_group`, `remove_flows_from_deployment_group`, `rename_deployment_group`, `start_deployment_group`, `stop_deployment_group`, `sync_deployment_group`, `delete_deployment_group`, `get_deployment_group_yamls`. Enforces the one-flow-one-group rule atomically.
+
+### Data Formats
+`list_data_formats`, `get_data_format`, `create_data_format`, `update_data_format`, `delete_data_format`, `add_attribute`, `update_attribute`, `remove_attribute`. Handles the rigid HRSF skeleton (Header/Records/Footer) for FLATFILE/TXT/CSV/DELIMITER.
+
+---
+
+## Docker
+
+```bash
+docker run -d --name dnio-mcp -p 3100:3100 \
+  -e DNIO_BASE_URL=https://your-datanimbus-instance.com \
+  -e DNIO_USERNAME=<admin-username> \
+  -e DNIO_PASSWORD=<admin-password> \
+  -e MCP_USER_EMAIL=<mcp-service-account-email> \
+  -e MCP_USER_PASSWORD=<mcp-service-account-password> \
+  -e TRANSPORT=http \
+  ghcr.io/datanimbus/dnio-mcp:latest
+```
+
+Or build from source — `Dockerfile` in repo root, K8s manifests in `yamls/`.
+
+---
+
+## Documentation
+
+- [`docs/architecture.md`](docs/architecture.md) — codebase layout, master client + per-domain pattern, transports.
+- [`docs/authentication.md`](docs/authentication.md) — token model, refresh lifecycle, app provisioning.
+- [`docs/workflows.md`](docs/workflows.md) — end-to-end recipes (build a data service, design a flow, deploy to K8s).
+- [`docs/tools/`](docs/tools/) — per-domain tool reference with endpoints + auto-injection rules.
+
+---
+
+## License
+
+ISC.

package/src/clients/api-keys.js

@@ -0,0 +1,10 @@
+'use strict';
+
+class ApiKeysClient {
+    constructor(http) {
+        this.http = http;
+    }
+    // TODO: implement DNIO API keys APIs
+}
+
+module.exports = ApiKeysClient;

package/src/clients/apps.js

@@ -0,0 +1,13 @@
+'use strict';
+
+class AppsClient {
+    constructor(http) {
+        this.http = http;
+    }
+
+    list() {
+        return this.http.get('api/a/rbac/admin/app?count=-1&select=_id,description');
+    }
+}
+
+module.exports = AppsClient;

package/src/clients/base-client.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const got = require('got');
+const logger = require('../utils/logger');
+
+class BaseClient {
+    constructor({baseUrl, token, timeout = 30000}) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.token = token || null;
+        this.timeout = timeout;
+        this._buildClient();
+    }
+
+    _buildClient() {
+        const headers = {'Content-Type': 'application/json'};
+        if (this.token) headers.Authorization = `JWT ${this.token}`;
+        this.client = got.extend({
+            prefixUrl: this.baseUrl,
+            timeout: {request: this.timeout},
+            headers,
+            responseType: 'json',
+            throwHttpErrors: false
+        });
+    }
+
+    setToken(token) {
+        this.token = token;
+        this._buildClient();
+    }
+
+    _logRequest(method, url, options) {
+        const [pathPart, queryString] = url.split('?');
+        const entry = {method, path: '/' + pathPart};
+        if (queryString) entry.query = Object.fromEntries(new URLSearchParams(queryString));
+        if (options.json !== undefined) entry.body = JSON.stringify(options.json);
+        logger.debug('DNIO API request', entry);
+    }
+
+    async _request(method, path, options = {}) {
+        const url = path.replace(/^\//, '');
+        this._logRequest(method, url, options);
+        try {
+            const response = await this.client(url, {method, ...options});
+            if (response.statusCode >= 400) {
+                const errMsg = response.body?.message || response.body?.error || `HTTP ${response.statusCode}`;
+                const err = new Error(errMsg);
+                err.status = response.statusCode;
+                err.body = response.body;
+                throw err;
+            }
+            return response.body;
+        } catch (error) {
+            if (error.status) throw error;
+            logger.error(`DNIO API error: ${method} ${path}`, {error: error.message});
+            const wrapped = new Error(error.message || 'DNIO API request failed');
+            wrapped.status = error.response?.statusCode || 502;
+            throw wrapped;
+        }
+    }
+
+    get(path, options) {
+        return this._request('GET', path, options);
+    }
+
+    post(path, body, options = {}) {
+        return this._request('POST', path, {...options, json: body});
+    }
+
+    put(path, body, options = {}) {
+        return this._request('PUT', path, {...options, json: body});
+    }
+
+    delete(path, options) {
+        return this._request('DELETE', path, options);
+    }
+}
+
+module.exports = BaseClient;

package/src/clients/bots.js

@@ -0,0 +1,10 @@
+'use strict';
+
+class BotsClient {
+    constructor(http) {
+        this.http = http;
+    }
+    // TODO: implement DNIO bots APIs
+}
+
+module.exports = BotsClient;

package/src/clients/connectors.js

@@ -0,0 +1,30 @@
+'use strict';
+
+class ConnectorsClient {
+    constructor(http) {
+        this.http = http;
+    }
+
+    list(appName, {category, count = -1, select} = {}) {
+        const filter = {app: appName};
+        if (category) filter.category = category;
+        const params = new URLSearchParams();
+        params.set('filter', JSON.stringify(filter));
+        params.set('count', String(count));
+        params.set('select', select || '_id,name,category,subCategory,type,options,_metadata');
+        return this.http.get(`api/a/rbac/${appName}/connector?${params.toString()}`);
+    }
+
+    listMarketTypes(appName, {count = 1000, select} = {}) {
+        const params = new URLSearchParams();
+        params.set('count', String(count));
+        params.set('select', select || 'label,thumbnail,type,fields,category,tags,version');
+        return this.http.get(`api/a/bm/${appName}/marketplace/connector?${params.toString()}`);
+    }
+
+    create(appName, payload) {
+        return this.http.post(`api/a/bm/${appName}/connector`, payload);
+    }
+}
+
+module.exports = ConnectorsClient;