nexinal — TypeScript/JavaScript Client for Nexuss Bash

A typed client library for interacting with the Nexuss Bash remote shell API.

Install

npm install nexinal

Quick Start

Basic Setup

import { NexussBash } from 'nexinal';

const nx = new NexussBash({
  host: 'http://localhost:3000',
  apiKey: 'your-api-key',
});

const result = await nx.run('echo "Hello from Nexuss Bash"');
console.log(result.stdout);

Running a Pipeline from YAML

const pipeline = await nx.pipelineRun({
  name: 'build-and-test',
  yaml: `
    steps:
      - run: npm ci
      - run: npm run build
      - run: npm test
  `,
});

console.log(pipeline.steps);

File Upload

const file = await nx.fileUpload('./data.csv', { path: '/workspace/data.csv' });
console.log(file.id, file.path);

Session Management

const session = await nx.sessionCreate({ name: 'dev-work' });
await nx.sessionExec(session.id, 'ls -la');
const logs = await nx.sessionLogs(session.id);
console.log(logs.entries);
await nx.sessionDelete(session.id);

Package Management

await nx.packageInstall('lodash');
const packages = await nx.packageList();
console.log(packages.packages);

Error Handling

import {
  NexussBash,
  AuthError,
  NotFoundError,
  ThrottledError,
} from 'nexinal';

const nx = new NexussBash({ host: 'http://localhost:3000', apiKey: 'bad-key' });

try {
  await nx.run('whoami');
} catch (err) {
  if (err instanceof AuthError) {
    console.error('Invalid API key');
  } else if (err instanceof NotFoundError) {
    console.error('Resource not found');
  } else if (err instanceof ThrottledError) {
    console.error('Rate limited, retry later');
  } else if (err instanceof NexussBashError) {
    console.error(err.message, err.status);
  }
}

API Reference

| Method | HTTP Call | Return Type | |---|---|---| | health() | GET /health | HealthResponse | | resources() | GET /resources | ResourceResponse | | systemInfo() | GET /system | SystemResponse | | run(command, opts?) | POST /run | RunResult | | runList(pagination?) | GET /run | RunListResponse | | sessionCreate(opts?) | POST /session | Session | | sessionList(pagination?) | GET /session | SessionListResponse | | sessionLogs(id) | GET /session/:id/logs | SessionLogs | | sessionExec(id, command) | POST /session/:id/exec | ExecResult | | sessionDelete(id) | DELETE /session/:id | void | | jobRun(language, opts?) | POST /job/:lang | JobRef | | jobDetail(id) | GET /job/:id | JobDetail | | jobList(language?, pagination?) | GET /job | JobListResponse | | jobCancel(id) | DELETE /job/:id | void | | jobLog(id) | GET /job/:id/log | string | | fileUpload(filePath, opts?) | POST /file | FileRecord | | fileList(pagination?) | GET /file | FileListResponse | | fileInfo(id) | GET /file/:id | FileRecord | | fileDelete(id) | DELETE /file/:id | void | | fileDownload(id) | GET /file/:id/download | Uint8Array | | pipelineRun(opts) | POST /pipeline | PipelineDetail | | pipelineDetail(id) | GET /pipeline/:id | PipelineDetail | | pipelineList(pagination?) | GET /pipeline | PipelineListResponse | | packageList(pagination?) | GET /package | PackageListResponse | | packageInstall(name) | POST /package/:name/install | PackageRecord | | packageUninstall(name) | DELETE /package/:name/install | void |

TypeScript Support

Full type definitions are included. All request options, responses, and error classes are fully typed.

import type { NexussBashConfig, RunResult, Session } from 'nexinal';

Requirements

• Node.js 18+ — uses native fetch.

License

MIT

Links

• GitHub Repository
• NPM Package
• Nexuss Bash API Docs