Host Management

/**
 * Creates a new HostClient instance
 * @param apiBase - Base URL for the Transform Hub API (e.g., "http://localhost:8000/api/v1")
 * @param utils - Optional custom ClientUtils instance for advanced configuration
 */
class HostClient implements ClientProvider {
  constructor(apiBase: string, utils?: ClientUtils);
  
  readonly apiBase: string;
  readonly client: ClientUtils;
}

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

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

/**
 * Lists all sequences available on the Hub
 * @returns Promise resolving to array of sequence information
 */
listSequences(): Promise<STHRestAPI.GetSequencesResponse[]>;

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

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

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

/**
 * Deletes a sequence from the Hub
 * @param sequenceId - Unique identifier of the sequence to delete
 * @param opts - Optional deletion options
 * @param opts.force - If true, forces deletion even if instances are running
 * @returns Promise resolving to deletion result
 */
deleteSequence(
  sequenceId: string,
  opts?: { force: boolean }
): Promise<STHRestAPI.DeleteSequenceResponse>;

// Upload a sequence
const sequenceStream = fs.createReadStream("./my-app.tar.gz");
const sequence = await host.sendSequence(sequenceStream);

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

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

/**
 * Lists all instances currently running on the Hub
 * @returns Promise resolving to array of instance information
 */
listInstances(): Promise<STHRestAPI.GetInstancesResponse>;

/**
 * Gets detailed information about a specific instance
 * @param instanceId - Unique identifier of the instance
 * @returns Promise resolving to instance details
 */
getInstanceInfo(instanceId: string): Promise<STHRestAPI.GetInstanceResponse>;

/**
 * Gets current Hub version information
 * @returns Promise resolving to version details
 */
getVersion(): Promise<STHRestAPI.GetVersionResponse>;

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

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

/**
 * Gets Hub public configuration
 * @returns Promise resolving to configuration data
 */
getConfig(): Promise<STHRestAPI.GetConfigResponse>;

/**
 * Lists all entities (sequences, instances, topics) on the Hub
 * @returns Promise resolving to entity list
 */
listEntities(): Promise<STHRestAPI.GetEntitiesResponse>;

/**
 * Gets Hub audit log stream for monitoring all activities
 * @param requestInit - Optional request configuration
 * @returns Promise resolving to readable stream of audit events
 */
getAuditStream(requestInit?: RequestInit): ReturnType<HttpClient["getStream"]>;

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

// Monitor system logs
const logStream = await host.getLogStream();
logStream.on('data', (chunk) => {
  console.log('Hub log:', chunk.toString());
});

/**
 * Creates an InstanceClient for managing a specific instance
 * @param id - Instance identifier
 * @returns InstanceClient instance
 */
getInstanceClient(id: string): InstanceClient;

/**
 * Creates a SequenceClient for managing a specific sequence
 * @param id - Sequence identifier
 * @returns SequenceClient instance
 */
getSequenceClient(id: string): SequenceClient;

/**
 * Creates a ManagerClient for advanced Hub management operations
 * @param apiBase - Optional API base path (defaults to "/api/v1")
 * @returns ManagerClient instance
 */
getManagerClient(apiBase?: string): ManagerClient;

/**
 * Sends data to a named topic
 * @param topic - Topic name
 * @param stream - Data stream to send
 * @param requestInit - Optional request configuration
 * @param contentType - Content type (defaults to "application/x-ndjson")
 * @param end - Whether to signal end of stream
 * @returns Promise resolving to send result
 */
sendTopic<T>(
  topic: string,
  stream: Parameters<HttpClient["sendStream"]>[1],
  requestInit?: RequestInit,
  contentType?: string,
  end?: boolean
): Promise<T>;

/**
 * Gets data stream from a named topic
 * @param topic - Topic name
 * @param requestInit - Optional request configuration
 * @param contentType - Expected content type (defaults to "application/x-ndjson")
 * @returns Promise resolving to readable stream
 */
getTopic(
  topic: string,
  requestInit?: RequestInit,
  contentType?: string
): ReturnType<HttpClient["getStream"]>;

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

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

/**
 * Lists all available topics
 * @returns Promise resolving to topics list
 */
getTopics(): Promise<STHRestAPI.GetTopicsResponse>;

// Convenience aliases
readonly sendNamedData: typeof sendTopic;
readonly getNamedData: typeof getTopic;

// Create and use a topic for data exchange
await host.createTopic("sensor-data", "application/json");

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

// Receive data from topic
const topicStream = await host.getTopic("sensor-data");
topicStream.on('data', (chunk) => {
  const data = JSON.parse(chunk.toString());
  console.log('Sensor reading:', data);
});

interface STHRestAPI {
  GetSequencesResponse: Array<{
    id: string;
    config: {
      name: string;
      version: string;
      description?: string;
      [key: string]: any;
    };
    instances: string[];
  }>;
  
  GetInstancesResponse: Array<{
    id: string;
    sequence: string;
    status: "starting" | "running" | "stopping" | "stopped" | "crashed";
    [key: string]: any;
  }>;
  
  GetSequenceResponse: {
    id: string;
    config: any;
    instances: string[];
  };
  
  GetInstanceResponse: {
    id: string;
    sequence: string;
    status: string;
    ports: any;
    [key: string]: any;
  };
  
  DeleteSequenceResponse: {
    id: string;
    message: string;
  };
  
  GetVersionResponse: {
    version: string;
    build?: string;
    [key: string]: any;
  };
  
  GetStatusResponse: {
    status: "ok" | "error";
    message?: string;
    [key: string]: any;
  };
  
  GetLoadCheckResponse: {
    avgLoad: number[];
    currentLoad: number;
    memUsage: number;
    [key: string]: any;
  };
  
  GetConfigResponse: {
    [key: string]: any;
  };
  
  GetEntitiesResponse: {
    sequences: string[];
    instances: string[];
    topics: string[];
  };
  
  GetTopicsResponse: Array<{
    id: string;
    contentType: string;
    [key: string]: any;
  }>;
}