0
# Host Management
1

2
The HostClient provides the primary interface for interacting with Transform Hub operations including sequence management, system monitoring, and service discovery.
3

4
## Capabilities
5

6
### Host Client Creation
7

8
Create a connection to Transform Hub.
9

10
```typescript { .api }
11
/**
12
 * Creates a new HostClient instance
13
 * @param apiBase - Base URL for the Transform Hub API (e.g., "http://localhost:8000/api/v1")
14
 * @param utils - Optional custom ClientUtils instance for advanced configuration
15
 */
16
class HostClient implements ClientProvider {
17
  constructor(apiBase: string, utils?: ClientUtils);
18
  
19
  readonly apiBase: string;
20
  readonly client: ClientUtils;
21
}
22
```
23

24
**Usage Example:**
25

26
```typescript
27
import { HostClient } from "@scramjet/api-client";
28

29
const host = new HostClient("http://localhost:8000/api/v1");
30
```
31

32
### Sequence Operations
33

34
Manage sequences (application packages) on the Hub.
35

36
```typescript { .api }
37
/**
38
 * Lists all sequences available on the Hub
39
 * @returns Promise resolving to array of sequence information
40
 */
41
listSequences(): Promise<STHRestAPI.GetSequencesResponse[]>;
42

43
/**
44
 * Gets sequence IDs by name
45
 * @param sequenceName - Name of the sequence to find
46
 * @returns Promise resolving to array of matching sequence IDs
47
 * @throws Error if no sequences found with the given name
48
 */
49
getSequenceId(sequenceName: string): Promise<string[]>;
50

51
/**
52
 * Uploads a sequence package to the Hub
53
 * @param sequencePackage - Stream containing the packaged sequence (e.g., tar.gz file)
54
 * @param requestInit - Optional request configuration
55
 * @returns Promise resolving to SequenceClient for the uploaded sequence
56
 */
57
sendSequence(
58
  sequencePackage: Parameters<HttpClient["sendStream"]>[1],
59
  requestInit?: RequestInit
60
): Promise<SequenceClient>;
61

62
/**
63
 * Gets detailed information about a specific sequence
64
 * @param sequenceId - Unique identifier of the sequence
65
 * @returns Promise resolving to sequence details
66
 */
67
getSequence(sequenceId: string): Promise<STHRestAPI.GetSequenceResponse>;
68

69
/**
70
 * Deletes a sequence from the Hub
71
 * @param sequenceId - Unique identifier of the sequence to delete
72
 * @param opts - Optional deletion options
73
 * @param opts.force - If true, forces deletion even if instances are running
74
 * @returns Promise resolving to deletion result
75
 */
76
deleteSequence(
77
  sequenceId: string,
78
  opts?: { force: boolean }
79
): Promise<STHRestAPI.DeleteSequenceResponse>;
80
```
81

82
**Usage Examples:**
83

84
```typescript
85
// Upload a sequence
86
const sequenceStream = fs.createReadStream("./my-app.tar.gz");
87
const sequence = await host.sendSequence(sequenceStream);
88

89
// List all sequences
90
const sequences = await host.listSequences();
91
console.log(`Found ${sequences.length} sequences`);
92

93
// Get sequence by name
94
const sequenceIds = await host.getSequenceId("my-app");
95
const sequenceClient = host.getSequenceClient(sequenceIds[0]);
96
```
97

98
### Instance Operations
99

100
Manage and monitor running instances.
101

102
```typescript { .api }
103
/**
104
 * Lists all instances currently running on the Hub
105
 * @returns Promise resolving to array of instance information
106
 */
107
listInstances(): Promise<STHRestAPI.GetInstancesResponse>;
108

109
/**
110
 * Gets detailed information about a specific instance
111
 * @param instanceId - Unique identifier of the instance
112
 * @returns Promise resolving to instance details
113
 */
114
getInstanceInfo(instanceId: string): Promise<STHRestAPI.GetInstanceResponse>;
115
```
116

117
### System Monitoring
118

119
Monitor Hub health and system status.
120

121
```typescript { .api }
122
/**
123
 * Gets current Hub version information
124
 * @returns Promise resolving to version details
125
 */
126
getVersion(): Promise<STHRestAPI.GetVersionResponse>;
127

128
/**
129
 * Gets current Hub status and health information
130
 * @returns Promise resolving to status details
131
 */
132
getStatus(): Promise<STHRestAPI.GetStatusResponse>;
133

134
/**
135
 * Gets current system load and resource usage
136
 * @returns Promise resolving to load check data
137
 */
138
getLoadCheck(): Promise<STHRestAPI.GetLoadCheckResponse>;
139

140
/**
141
 * Gets Hub public configuration
142
 * @returns Promise resolving to configuration data
143
 */
144
getConfig(): Promise<STHRestAPI.GetConfigResponse>;
145

146
/**
147
 * Lists all entities (sequences, instances, topics) on the Hub
148
 * @returns Promise resolving to entity list
149
 */
150
listEntities(): Promise<STHRestAPI.GetEntitiesResponse>;
151
```
152

153
### Streaming Operations
154

155
Access real-time log and audit streams.
156

157
```typescript { .api }
158
/**
159
 * Gets Hub audit log stream for monitoring all activities
160
 * @param requestInit - Optional request configuration
161
 * @returns Promise resolving to readable stream of audit events
162
 */
163
getAuditStream(requestInit?: RequestInit): ReturnType<HttpClient["getStream"]>;
164

165
/**
166
 * Gets Hub system log stream
167
 * @param requestInit - Optional request configuration
168
 * @returns Promise resolving to readable stream of system logs
169
 */
170
getLogStream(requestInit?: RequestInit): ReturnType<HttpClient["getStream"]>;
171
```
172

173
**Usage Example:**
174

175
```typescript
176
// Monitor system logs
177
const logStream = await host.getLogStream();
178
logStream.on('data', (chunk) => {
179
  console.log('Hub log:', chunk.toString());
180
});
181
```
182

183
### Client Factories
184

185
Create specialized client instances for specific operations.
186

187
```typescript { .api }
188
/**
189
 * Creates an InstanceClient for managing a specific instance
190
 * @param id - Instance identifier
191
 * @returns InstanceClient instance
192
 */
193
getInstanceClient(id: string): InstanceClient;
194

195
/**
196
 * Creates a SequenceClient for managing a specific sequence
197
 * @param id - Sequence identifier
198
 * @returns SequenceClient instance
199
 */
200
getSequenceClient(id: string): SequenceClient;
201

202
/**
203
 * Creates a ManagerClient for advanced Hub management operations
204
 * @param apiBase - Optional API base path (defaults to "/api/v1")
205
 * @returns ManagerClient instance
206
 */
207
getManagerClient(apiBase?: string): ManagerClient;
208
```
209

210
### Topics and Service Discovery
211

212
Manage topics for data exchange between sequences and external systems.
213

214
```typescript { .api }
215
/**
216
 * Sends data to a named topic
217
 * @param topic - Topic name
218
 * @param stream - Data stream to send
219
 * @param requestInit - Optional request configuration
220
 * @param contentType - Content type (defaults to "application/x-ndjson")
221
 * @param end - Whether to signal end of stream
222
 * @returns Promise resolving to send result
223
 */
224
sendTopic<T>(
225
  topic: string,
226
  stream: Parameters<HttpClient["sendStream"]>[1],
227
  requestInit?: RequestInit,
228
  contentType?: string,
229
  end?: boolean
230
): Promise<T>;
231

232
/**
233
 * Gets data stream from a named topic
234
 * @param topic - Topic name
235
 * @param requestInit - Optional request configuration
236
 * @param contentType - Expected content type (defaults to "application/x-ndjson")
237
 * @returns Promise resolving to readable stream
238
 */
239
getTopic(
240
  topic: string,
241
  requestInit?: RequestInit,
242
  contentType?: string
243
): ReturnType<HttpClient["getStream"]>;
244

245
/**
246
 * Creates a new topic
247
 * @param id - Topic identifier
248
 * @param contentType - Content type for the topic
249
 * @returns Promise resolving to topic creation result
250
 */
251
createTopic(id: string, contentType: string): Promise<{ topicName: string }>;
252

253
/**
254
 * Deletes a topic
255
 * @param id - Topic identifier
256
 * @returns Promise resolving to deletion result
257
 */
258
deleteTopic(id: string): Promise<{ message: string }>;
259

260
/**
261
 * Lists all available topics
262
 * @returns Promise resolving to topics list
263
 */
264
getTopics(): Promise<STHRestAPI.GetTopicsResponse>;
265

266
// Convenience aliases
267
readonly sendNamedData: typeof sendTopic;
268
readonly getNamedData: typeof getTopic;
269
```
270

271
**Usage Example:**
272

273
```typescript
274
// Create and use a topic for data exchange
275
await host.createTopic("sensor-data", "application/json");
276

277
// Send data to topic
278
const dataStream = Readable.from([
279
  JSON.stringify({ temperature: 22.5, humidity: 60 }),
280
  JSON.stringify({ temperature: 23.1, humidity: 58 })
281
]);
282
await host.sendTopic("sensor-data", dataStream);
283

284
// Receive data from topic
285
const topicStream = await host.getTopic("sensor-data");
286
topicStream.on('data', (chunk) => {
287
  const data = JSON.parse(chunk.toString());
288
  console.log('Sensor reading:', data);
289
});
290
```
291

292
## Response Types
293

294
```typescript { .api }
295
interface STHRestAPI {
296
  GetSequencesResponse: Array<{
297
    id: string;
298
    config: {
299
      name: string;
300
      version: string;
301
      description?: string;
302
      [key: string]: any;
303
    };
304
    instances: string[];
305
  }>;
306
  
307
  GetInstancesResponse: Array<{
308
    id: string;
309
    sequence: string;
310
    status: "starting" | "running" | "stopping" | "stopped" | "crashed";
311
    [key: string]: any;
312
  }>;
313
  
314
  GetSequenceResponse: {
315
    id: string;
316
    config: any;
317
    instances: string[];
318
  };
319
  
320
  GetInstanceResponse: {
321
    id: string;
322
    sequence: string;
323
    status: string;
324
    ports: any;
325
    [key: string]: any;
326
  };
327
  
328
  DeleteSequenceResponse: {
329
    id: string;
330
    message: string;
331
  };
332
  
333
  GetVersionResponse: {
334
    version: string;
335
    build?: string;
336
    [key: string]: any;
337
  };
338
  
339
  GetStatusResponse: {
340
    status: "ok" | "error";
341
    message?: string;
342
    [key: string]: any;
343
  };
344
  
345
  GetLoadCheckResponse: {
346
    avgLoad: number[];
347
    currentLoad: number;
348
    memUsage: number;
349
    [key: string]: any;
350
  };
351
  
352
  GetConfigResponse: {
353
    [key: string]: any;
354
  };
355
  
356
  GetEntitiesResponse: {
357
    sequences: string[];
358
    instances: string[];
359
    topics: string[];
360
  };
361
  
362
  GetTopicsResponse: Array<{
363
    id: string;
364
    contentType: string;
365
    [key: string]: any;
366
  }>;
367
}
368
```