0
# Scramjet Transform Hub API Client
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @scramjet/api-client
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @scramjet/api-client`
10

11
## Core Imports
12

13
```typescript
14
import { HostClient, InstanceClient, SequenceClient, ManagerClient } from "@scramjet/api-client";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { HostClient, InstanceClient, SequenceClient, ManagerClient } = require("@scramjet/api-client");
21
```
22

23
Type-only imports:
24

25
```typescript
26
import type { InstanceInputStream, InstanceOutputStream } from "@scramjet/api-client";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { HostClient } from "@scramjet/api-client";
33
import { Readable } from "stream";
34

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

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

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

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

50
// Stop instance when done
51
await instance.stop(5000, false);
52
```
53

54
## Architecture
55

56
The API client is built around several key components:
57

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

65
## Capabilities
66

67
### Host Management
68

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

71
```typescript { .api }
72
class HostClient {
73
  constructor(apiBase: string, utils?: ClientUtils);
74
  
75
  // Sequence operations
76
  listSequences(): Promise<STHRestAPI.GetSequencesResponse[]>;
77
  getSequenceId(sequenceName: string): Promise<string[]>;
78
  sendSequence(sequencePackage: Parameters<HttpClient["sendStream"]>[1], requestInit?: RequestInit): Promise<SequenceClient>;
79
  getSequence(sequenceId: string): Promise<STHRestAPI.GetSequenceResponse>;
80
  deleteSequence(sequenceId: string, opts?: { force: boolean }): Promise<STHRestAPI.DeleteSequenceResponse>;
81
  
82
  // Instance operations
83
  listInstances(): Promise<STHRestAPI.GetInstancesResponse>;
84
  getInstanceInfo(instanceId: string): Promise<STHRestAPI.GetInstanceResponse>;
85
  
86
  // System monitoring
87
  listEntities(): Promise<STHRestAPI.GetEntitiesResponse>;
88
  getVersion(): Promise<STHRestAPI.GetVersionResponse>;
89
  getStatus(): Promise<STHRestAPI.GetStatusResponse>;
90
  getLoadCheck(): Promise<STHRestAPI.GetLoadCheckResponse>;
91
  getConfig(): Promise<STHRestAPI.GetConfigResponse>;
92
  getAuditStream(requestInit?: RequestInit): ReturnType<HttpClient["getStream"]>;
93
  getLogStream(requestInit?: RequestInit): ReturnType<HttpClient["getStream"]>;
94
  
95
  // Topics and service discovery
96
  sendTopic<T>(topic: string, stream: Parameters<HttpClient["sendStream"]>[1], requestInit?: RequestInit, contentType?: string, end?: boolean): Promise<T>;
97
  getTopic(topic: string, requestInit?: RequestInit, contentType?: string): ReturnType<HttpClient["getStream"]>;
98
  createTopic(id: string, contentType: string): Promise<{ topicName: string }>;
99
  deleteTopic(id: string): Promise<{ message: string }>;
100
  getTopics(): Promise<STHRestAPI.GetTopicsResponse>;
101
  readonly sendNamedData: typeof sendTopic;
102
  readonly getNamedData: typeof getTopic;
103
  
104
  // Client factories
105
  getInstanceClient(id: string): InstanceClient;
106
  getSequenceClient(id: string): SequenceClient;
107
  getManagerClient(apiBase?: string): ManagerClient;
108
}
109
```
110

111
[Host Management](./host-client.md)
112

113
### Sequence Management
114

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

117
```typescript { .api }
118
class SequenceClient {
119
  readonly id: string;
120
  
121
  static from(id: string, host: ClientProvider): SequenceClient;
122
  
123
  start(payload: STHRestAPI.StartSequencePayload): Promise<InstanceClient>;
124
  listInstances(): Promise<string[]>;
125
  getInstance(id: string, host?: ClientProvider): Promise<InstanceClient>;
126
  getInfo(): Promise<STHRestAPI.GetSequenceResponse>;
127
  overwrite(stream: Readable): Promise<SequenceClient>;
128
}
129
```
130

131
[Sequence Management](./sequence-client.md)
132

133
### Instance Control
134

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

137
```typescript { .api }
138
class InstanceClient {
139
  readonly id: string;
140
  
141
  static from(id: string, host: ClientProvider): InstanceClient;
142
  
143
  // Lifecycle
144
  stop(timeout: number, canCallKeepalive: boolean): Promise<STHRestAPI.SendStopInstanceResponse>;
145
  kill(opts?: KillMessageData): Promise<STHRestAPI.SendKillInstanceResponse>;
146
  getHealth(): Promise<STHRestAPI.GetHealthResponse>;
147
  getInfo(): Promise<STHRestAPI.GetInstanceResponse>;
148
  
149
  // Streaming
150
  getStream(streamId: InstanceOutputStream): ReturnType<HttpClient["getStream"]>;
151
  sendStream(streamId: InstanceInputStream, stream: Parameters<HttpClient["sendStream"]>[1] | string, requestInit?: RequestInit, options?: SendStreamOptions): Promise<STHRestAPI.SendStreamResponse>;
152
  sendInput(stream: Parameters<HttpClient["sendStream"]>[1] | string, requestInit?: RequestInit, options?: SendStreamOptions): Promise<STHRestAPI.SendStreamResponse>;
153
  sendStdin(stream: Parameters<HttpClient["sendStream"]>[1] | string): Promise<STHRestAPI.SendStreamResponse>;
154
  inout(stream: Parameters<HttpClient["sendStream"]>[1], requestInit?: RequestInit, options?: SendStreamOptions): Promise<any>;
155
  getLogStream(): Promise<Readable>;
156
  
157
  // Events
158
  sendEvent(eventName: string, message: string): Promise<STHRestAPI.SendEventResponse>;
159
  getNextEvent(eventName: string): Promise<STHRestAPI.GetEventResponse>;
160
  getEvent(eventName: string): Promise<STHRestAPI.GetEventResponse>;
161
  getEventStream(eventName: string): Promise<Readable>;
162
}
163

164
type InstanceInputStream = "stdin" | "input";
165
type InstanceOutputStream = "stdout" | "stderr" | "output" | "log";
166
```
167

168
[Instance Control](./instance-client.md)
169

170
### Manager Operations
171

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

174
```typescript { .api }
175
class ManagerClient {
176
  constructor(apiBase: string, utils?: ClientUtils);
177
  
178
  // Hub management
179
  getHosts(): Promise<MRestAPI.GetHostInfoResponse[]>;
180
  getHostClient(id: string, hostApiBase?: string): HostClient;
181
  deleteHub(id: string, force: boolean): Promise<MRestAPI.HubDeleteResponse>;
182
  disconnectHubs(opts: MRestAPI.PostDisconnectPayload): Promise<MRestAPI.PostDisconnectResponse>;
183
  
184
  // System monitoring
185
  getVersion(): Promise<MRestAPI.GetVersionResponse>;
186
  getLoad(): Promise<LoadCheckStat>;
187
  getConfig(): Promise<any>;
188
  
189
  // Cross-hub operations
190
  getAllSequences(): Promise<MRestAPI.GetSequencesResponse>;
191
  getSequences(): Promise<MRestAPI.GetSequencesResponse>;
192
  getInstances(): Promise<MRestAPI.GetInstancesResponse>;
193
  getTopics(): Promise<MRestAPI.GetTopicsResponse>;
194
  
195
  // Store operations
196
  getStoreItems(): Promise<MRestAPI.GetStoreItemsResponse>;
197
  putStoreItem(sequencePackage: Readable, id?: string): Promise<MRestAPI.PutStoreItemResponse>;
198
  deleteStoreItem(id: string): Promise<void>;
199
  clearStore(): Promise<void>;
200
  
201
  // Streaming operations
202
  sendNamedData<T>(topic: string, stream: Parameters<HttpClient["sendStream"]>[1], requestInit?: RequestInit, contentType?: string, end?: boolean): Promise<T>;
203
  getNamedData(topic: string, requestInit?: RequestInit): Promise<Readable>;
204
  getLogStream(requestInit?: RequestInit): Promise<Readable>;
205
  getAuditStream(requestInit?: RequestInit): Promise<Readable>;
206
}
207
```
208

209
[Manager Operations](./manager-client.md)
210

211
### Topics and Service Discovery
212

213
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.
214

215
[Topics and Service Discovery](./topics.md)
216

217
## Common Types
218

219
```typescript { .api }
220
interface ClientProvider {
221
  client: ClientUtils;
222
}
223

224
interface STHRestAPI {
225
  GetSequencesResponse: Array<{
226
    id: string;
227
    config: SequenceConfig;
228
    instances: string[];
229
  }>;
230
  
231
  StartSequencePayload: {
232
    appConfig?: any;
233
    args?: string[];
234
    [key: string]: any;
235
  };
236
  
237
  // ... other response types
238
}
239

240
interface SendStreamOptions {
241
  type?: string;
242
  end?: boolean;
243
  parseResponse?: "json" | "text" | "stream";
244
  json?: boolean;
245
  parse?: "json" | "text" | "stream";
246
}
247
```