or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

host-client.mdindex.mdinstance-client.mdmanager-client.mdsequence-client.mdtopics.md
tile.json

tessl/npm-scramjet--api-client

API Client for use with Scramjet Transform Hub providing typed interfaces for managing sequences, instances, and Hub operations

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@scramjet/api-client@1.0.x

To install, run

npx @tessl/cli install tessl/npm-scramjet--api-client@1.0.0

index.mddocs/

Scramjet Transform Hub API Client

Scramjet Transform Hub API Client provides a comprehensive TypeScript library for interacting with Scramjet Transform Hub - a deployment and execution platform for containerized applications. The client enables developers to programmatically manage sequences (applications), instances (running processes), and various Hub operations through clean, typed JavaScript/TypeScript interfaces.

Package Information

  • Package Name: @scramjet/api-client
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @scramjet/api-client

Core Imports

import { HostClient, InstanceClient, SequenceClient, ManagerClient } from "@scramjet/api-client";

For CommonJS:

const { HostClient, InstanceClient, SequenceClient, ManagerClient } = require("@scramjet/api-client");

Type-only imports:

import type { InstanceInputStream, InstanceOutputStream } from "@scramjet/api-client";

Basic Usage

import { HostClient } from "@scramjet/api-client";
import { Readable } from "stream";

// Connect to Transform Hub
const host = new HostClient("http://localhost:8000/api/v1");

// Upload and start a sequence
const sequencePackage = fs.createReadStream("./my-sequence.tar.gz");
const sequence = await host.sendSequence(sequencePackage);
const instance = await sequence.start({});

// Monitor instance output
const outputStream = await instance.getStream("output");
outputStream.pipe(process.stdout);

// Send data to instance
await instance.sendInput("Hello, World!");

// Stop instance when done
await instance.stop(5000, false);

Architecture

The API client is built around several key components:

  • HostClient: Primary interface for Hub-level operations including sequence management, instance listing, and system monitoring
  • SequenceClient: Manages individual sequences with capabilities for starting instances and sequence metadata operations
  • InstanceClient: Controls running sequence instances with stream I/O, event handling, and lifecycle management
  • ManagerClient: Advanced client for multi-hub scenarios and store operations
  • Streaming Support: Full support for bidirectional streaming operations with proper backpressure handling
  • Type Safety: Complete TypeScript integration with typed responses and proper error handling

Capabilities

Host Management

Core Hub operations including sequence upload, system monitoring, and service discovery through topics.

class HostClient {
  constructor(apiBase: string, utils?: ClientUtils);
  
  // Sequence operations
  listSequences(): Promise<STHRestAPI.GetSequencesResponse[]>;
  getSequenceId(sequenceName: string): Promise<string[]>;
  sendSequence(sequencePackage: Parameters<HttpClient["sendStream"]>[1], requestInit?: RequestInit): Promise<SequenceClient>;
  getSequence(sequenceId: string): Promise<STHRestAPI.GetSequenceResponse>;
  deleteSequence(sequenceId: string, opts?: { force: boolean }): Promise<STHRestAPI.DeleteSequenceResponse>;
  
  // Instance operations
  listInstances(): Promise<STHRestAPI.GetInstancesResponse>;
  getInstanceInfo(instanceId: string): Promise<STHRestAPI.GetInstanceResponse>;
  
  // System monitoring
  listEntities(): Promise<STHRestAPI.GetEntitiesResponse>;
  getVersion(): Promise<STHRestAPI.GetVersionResponse>;
  getStatus(): Promise<STHRestAPI.GetStatusResponse>;
  getLoadCheck(): Promise<STHRestAPI.GetLoadCheckResponse>;
  getConfig(): Promise<STHRestAPI.GetConfigResponse>;
  getAuditStream(requestInit?: RequestInit): ReturnType<HttpClient["getStream"]>;
  getLogStream(requestInit?: RequestInit): ReturnType<HttpClient["getStream"]>;
  
  // Topics and service discovery
  sendTopic<T>(topic: string, stream: Parameters<HttpClient["sendStream"]>[1], requestInit?: RequestInit, contentType?: string, end?: boolean): Promise<T>;
  getTopic(topic: string, requestInit?: RequestInit, contentType?: string): ReturnType<HttpClient["getStream"]>;
  createTopic(id: string, contentType: string): Promise<{ topicName: string }>;
  deleteTopic(id: string): Promise<{ message: string }>;
  getTopics(): Promise<STHRestAPI.GetTopicsResponse>;
  readonly sendNamedData: typeof sendTopic;
  readonly getNamedData: typeof getTopic;
  
  // Client factories
  getInstanceClient(id: string): InstanceClient;
  getSequenceClient(id: string): SequenceClient;
  getManagerClient(apiBase?: string): ManagerClient;
}

Host Management

Sequence Management

Operations for managing sequences (application packages) including starting instances and metadata access.

class SequenceClient {
  readonly id: string;
  
  static from(id: string, host: ClientProvider): SequenceClient;
  
  start(payload: STHRestAPI.StartSequencePayload): Promise<InstanceClient>;
  listInstances(): Promise<string[]>;
  getInstance(id: string, host?: ClientProvider): Promise<InstanceClient>;
  getInfo(): Promise<STHRestAPI.GetSequenceResponse>;
  overwrite(stream: Readable): Promise<SequenceClient>;
}

Sequence Management

Instance Control

Comprehensive instance lifecycle management with streaming I/O, event handling, and process control.

class InstanceClient {
  readonly id: string;
  
  static from(id: string, host: ClientProvider): InstanceClient;
  
  // Lifecycle
  stop(timeout: number, canCallKeepalive: boolean): Promise<STHRestAPI.SendStopInstanceResponse>;
  kill(opts?: KillMessageData): Promise<STHRestAPI.SendKillInstanceResponse>;
  getHealth(): Promise<STHRestAPI.GetHealthResponse>;
  getInfo(): Promise<STHRestAPI.GetInstanceResponse>;
  
  // Streaming
  getStream(streamId: InstanceOutputStream): ReturnType<HttpClient["getStream"]>;
  sendStream(streamId: InstanceInputStream, stream: Parameters<HttpClient["sendStream"]>[1] | string, requestInit?: RequestInit, options?: SendStreamOptions): Promise<STHRestAPI.SendStreamResponse>;
  sendInput(stream: Parameters<HttpClient["sendStream"]>[1] | string, requestInit?: RequestInit, options?: SendStreamOptions): Promise<STHRestAPI.SendStreamResponse>;
  sendStdin(stream: Parameters<HttpClient["sendStream"]>[1] | string): Promise<STHRestAPI.SendStreamResponse>;
  inout(stream: Parameters<HttpClient["sendStream"]>[1], requestInit?: RequestInit, options?: SendStreamOptions): Promise<any>;
  getLogStream(): Promise<Readable>;
  
  // Events
  sendEvent(eventName: string, message: string): Promise<STHRestAPI.SendEventResponse>;
  getNextEvent(eventName: string): Promise<STHRestAPI.GetEventResponse>;
  getEvent(eventName: string): Promise<STHRestAPI.GetEventResponse>;
  getEventStream(eventName: string): Promise<Readable>;
}

type InstanceInputStream = "stdin" | "input";
type InstanceOutputStream = "stdout" | "stderr" | "output" | "log";

Instance Control

Manager Operations

Advanced operations for multi-hub environments including hub management and distributed store operations.

class ManagerClient {
  constructor(apiBase: string, utils?: ClientUtils);
  
  // Hub management
  getHosts(): Promise<MRestAPI.GetHostInfoResponse[]>;
  getHostClient(id: string, hostApiBase?: string): HostClient;
  deleteHub(id: string, force: boolean): Promise<MRestAPI.HubDeleteResponse>;
  disconnectHubs(opts: MRestAPI.PostDisconnectPayload): Promise<MRestAPI.PostDisconnectResponse>;
  
  // System monitoring
  getVersion(): Promise<MRestAPI.GetVersionResponse>;
  getLoad(): Promise<LoadCheckStat>;
  getConfig(): Promise<any>;
  
  // Cross-hub operations
  getAllSequences(): Promise<MRestAPI.GetSequencesResponse>;
  getSequences(): Promise<MRestAPI.GetSequencesResponse>;
  getInstances(): Promise<MRestAPI.GetInstancesResponse>;
  getTopics(): Promise<MRestAPI.GetTopicsResponse>;
  
  // Store operations
  getStoreItems(): Promise<MRestAPI.GetStoreItemsResponse>;
  putStoreItem(sequencePackage: Readable, id?: string): Promise<MRestAPI.PutStoreItemResponse>;
  deleteStoreItem(id: string): Promise<void>;
  clearStore(): Promise<void>;
  
  // Streaming operations
  sendNamedData<T>(topic: string, stream: Parameters<HttpClient["sendStream"]>[1], requestInit?: RequestInit, contentType?: string, end?: boolean): Promise<T>;
  getNamedData(topic: string, requestInit?: RequestInit): Promise<Readable>;
  getLogStream(requestInit?: RequestInit): Promise<Readable>;
  getAuditStream(requestInit?: RequestInit): Promise<Readable>;
}

Manager Operations

Topics and Service Discovery

Service discovery through topics API enabling data exchange between sequences and external systems. Topics operations are available through HostClient and are covered in the Host Management section above.

Topics and Service Discovery

Common Types

interface ClientProvider {
  client: ClientUtils;
}

interface STHRestAPI {
  GetSequencesResponse: Array<{
    id: string;
    config: SequenceConfig;
    instances: string[];
  }>;
  
  StartSequencePayload: {
    appConfig?: any;
    args?: string[];
    [key: string]: any;
  };
  
  // ... other response types
}

interface SendStreamOptions {
  type?: string;
  end?: boolean;
  parseResponse?: "json" | "text" | "stream";
  json?: boolean;
  parse?: "json" | "text" | "stream";
}