colonies-ts 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,274 @@
+/**
+ * Generate a new random private key
+ * @returns Hex-encoded private key (64 characters)
+ */
+declare function generatePrivateKey(): string;
+/**
+ * Derive the public ID from a private key
+ * Uses SHA3-256 hash of "04" + hex(publicKey)
+ * @param privateKey - Hex-encoded private key
+ * @returns Hex-encoded ID (64 characters)
+ */
+declare function deriveId(privateKey: string): string;
+/**
+ * Sign a message with a private key
+ * @param message - Message to sign
+ * @param privateKey - Hex-encoded private key
+ * @returns Hex-encoded signature (130 characters: r + s + v)
+ */
+declare function sign(message: string, privateKey: string): string;
+/**
+ * Crypto utility class for convenience
+ */
+declare class Crypto {
+    generatePrivateKey(): string;
+    id(privateKey: string): string;
+    sign(message: string, privateKey: string): string;
+}
+
+/**
+ * ColonyOS Client
+ * Ported from colonyspace/aila/src/lib/api/colony.ts
+ */
+interface ColoniesClientConfig {
+    host: string;
+    port: number;
+    tls?: boolean;
+}
+interface RPCMessage {
+    payloadtype: string;
+    payload: string;
+    signature: string;
+}
+interface FunctionSpec {
+    nodename?: string;
+    funcname: string;
+    args?: any[];
+    kwargs?: Record<string, any>;
+    priority?: number;
+    maxwaittime?: number;
+    maxexectime?: number;
+    maxretries?: number;
+    conditions?: {
+        colonyname?: string;
+        executornames?: string[];
+        executortype?: string;
+        dependencies?: string[];
+        nodes?: number;
+        cpu?: string;
+        processes?: number;
+        processespernode?: number;
+        mem?: string;
+        storage?: string;
+        gpu?: {
+            name?: string;
+            mem?: string;
+            count?: number;
+            nodecount?: number;
+        };
+        walltime?: number;
+    };
+    label?: string;
+    fs?: any;
+    env?: Record<string, string>;
+    channels?: string[];
+}
+declare enum ProcessState {
+    WAITING = 0,
+    RUNNING = 1,
+    SUCCESS = 2,
+    FAILED = 3
+}
+declare class ColoniesClient {
+    private host;
+    private port;
+    private tls;
+    private crypto;
+    private privateKey;
+    constructor(config: ColoniesClientConfig);
+    setPrivateKey(privateKey: string): void;
+    private getBaseUrl;
+    private createRPCMsg;
+    private sendRPC;
+    getColonies(): Promise<any>;
+    getStatistics(): Promise<any>;
+    /**
+     * Add a new colony (requires server private key)
+     * @param colony - Colony object with colonyid and name
+     */
+    addColony(colony: {
+        colonyid: string;
+        name: string;
+    }): Promise<any>;
+    /**
+     * Remove a colony (requires server private key)
+     * @param colonyName - Name of the colony to remove
+     */
+    removeColony(colonyName: string): Promise<any>;
+    getExecutors(colonyName: string): Promise<any>;
+    getExecutor(colonyName: string, executorName: string): Promise<any>;
+    addExecutor(executor: {
+        executorid: string;
+        executortype: string;
+        executorname: string;
+        colonyname: string;
+    }): Promise<any>;
+    approveExecutor(colonyName: string, executorName: string): Promise<any>;
+    removeExecutor(colonyName: string, executorName: string): Promise<any>;
+    submitFunctionSpec(spec: FunctionSpec): Promise<any>;
+    getProcess(processId: string): Promise<any>;
+    getProcesses(colonyName: string, count: number, state: ProcessState): Promise<any>;
+    removeProcess(processId: string): Promise<any>;
+    removeAllProcesses(colonyName: string, state?: number): Promise<any>;
+    assign(colonyName: string, timeout: number, executorPrvKey: string): Promise<any>;
+    closeProcess(processId: string, output: string[]): Promise<any>;
+    failProcess(processId: string, errors: string[]): Promise<any>;
+    submitWorkflowSpec(workflowSpec: {
+        colonyname: string;
+        functionspecs: FunctionSpec[];
+    }): Promise<any>;
+    getProcessGraph(processGraphId: string): Promise<any>;
+    getProcessGraphs(colonyName: string, count: number, state?: ProcessState): Promise<any>;
+    removeProcessGraph(processGraphId: string): Promise<any>;
+    removeAllProcessGraphs(colonyName: string, state?: ProcessState): Promise<any>;
+    addLog(processId: string, message: string, executorPrvKey: string): Promise<any>;
+    getLogs(colonyName: string, processId: string, executorName: string, count?: number, since?: number): Promise<any>;
+    getFunctions(executorName: string, colonyName: string): Promise<any>;
+    getCrons(colonyName: string, count?: number): Promise<any>;
+    getCron(cronId: string): Promise<any>;
+    addCron(cronSpec: any): Promise<any>;
+    removeCron(cronId: string): Promise<any>;
+    getGenerators(colonyName: string, count?: number): Promise<any>;
+    getGenerator(generatorId: string): Promise<any>;
+    addGenerator(generatorSpec: any): Promise<any>;
+    getUsers(colonyName: string): Promise<any>;
+    addUser(user: {
+        colonyname: string;
+        userid: string;
+        name: string;
+        email: string;
+        phone: string;
+    }): Promise<any>;
+    removeUser(colonyName: string, name: string): Promise<any>;
+    getFileLabels(colonyName: string, name?: string, exact?: boolean): Promise<any>;
+    getFiles(colonyName: string, label: string): Promise<any>;
+    addAttribute(attribute: {
+        targetid: string;
+        targetcolonyname: string;
+        targetprocessgraphid: string;
+        attributetype: number;
+        key: string;
+        value: string;
+    }): Promise<any>;
+    getAttribute(attributeId: string): Promise<any>;
+    /**
+     * Append a message to a process channel
+     * @param processId - ID of the process
+     * @param channelName - Name of the channel
+     * @param sequence - Client-assigned sequence number
+     * @param inReplyTo - Sequence number this message is replying to (0 if not a reply)
+     * @param payload - Message content (string or Uint8Array)
+     */
+    channelAppend(processId: string, channelName: string, sequence: number, inReplyTo: number, payload: string | Uint8Array): Promise<any>;
+    /**
+     * Read messages from a process channel
+     * @param processId - ID of the process
+     * @param channelName - Name of the channel
+     * @param afterSeq - Read messages after this sequence number (use 0 for all)
+     * @param limit - Maximum number of messages to return (0 for no limit)
+     */
+    channelRead(processId: string, channelName: string, afterSeq: number, limit: number): Promise<any[]>;
+    /**
+     * Subscribe to a channel using WebSocket for real-time updates
+     * @param processId - ID of the process
+     * @param channelName - Name of the channel
+     * @param afterSeq - Start reading after this sequence number
+     * @param timeout - Timeout in seconds for the subscription
+     * @param onMessage - Callback for new messages
+     * @param onError - Callback for errors
+     * @param onClose - Callback when connection closes
+     * @returns WebSocket instance for cleanup
+     */
+    subscribeChannel(processId: string, channelName: string, afterSeq: number, timeout: number, onMessage: (entries: any[]) => void, onError: (error: Error) => void, onClose: () => void): WebSocket;
+    /**
+     * Add a blueprint definition
+     * @param definition - Blueprint definition object
+     */
+    addBlueprintDefinition(definition: any): Promise<any>;
+    /**
+     * Get a blueprint definition by name
+     * @param colonyName - Name of the colony
+     * @param name - Name of the blueprint definition
+     */
+    getBlueprintDefinition(colonyName: string, name: string): Promise<any>;
+    /**
+     * Get all blueprint definitions in a colony
+     * @param colonyName - Name of the colony
+     */
+    getBlueprintDefinitions(colonyName: string): Promise<any[]>;
+    /**
+     * Remove a blueprint definition
+     * @param colonyName - Name of the colony (namespace)
+     * @param name - Name of the blueprint definition to remove
+     */
+    removeBlueprintDefinition(colonyName: string, name: string): Promise<void>;
+    /**
+     * Add a blueprint instance
+     * @param blueprint - Blueprint object
+     */
+    addBlueprint(blueprint: any): Promise<any>;
+    /**
+     * Get a blueprint by name
+     * @param colonyName - Name of the colony (namespace)
+     * @param name - Name of the blueprint
+     */
+    getBlueprint(colonyName: string, name: string): Promise<any>;
+    /**
+     * Get blueprints in a colony, optionally filtered by kind and location
+     * @param colonyName - Name of the colony (namespace)
+     * @param kind - Optional kind filter
+     * @param location - Optional location filter
+     */
+    getBlueprints(colonyName: string, kind?: string, location?: string): Promise<any[]>;
+    /**
+     * Update an existing blueprint
+     * @param blueprint - Updated blueprint object
+     * @param forceGeneration - Force generation bump even if spec unchanged
+     */
+    updateBlueprint(blueprint: any, forceGeneration?: boolean): Promise<any>;
+    /**
+     * Remove a blueprint
+     * @param colonyName - Name of the colony (namespace)
+     * @param name - Name of the blueprint to remove
+     */
+    removeBlueprint(colonyName: string, name: string): Promise<void>;
+    /**
+     * Update blueprint status (current state)
+     * @param colonyName - Name of the colony
+     * @param name - Name of the blueprint
+     * @param status - Status object representing current state
+     */
+    updateBlueprintStatus(colonyName: string, name: string, status: any): Promise<void>;
+    /**
+     * Trigger reconciliation for a blueprint
+     * @param colonyName - Name of the colony (namespace)
+     * @param name - Name of the blueprint
+     * @param force - Force reconciliation even if no changes detected
+     */
+    reconcileBlueprint(colonyName: string, name: string, force?: boolean): Promise<any>;
+    /**
+     * Subscribe to process state changes using WebSocket
+     * Use this to wait for a process to be assigned (RUNNING state) before subscribing to channels
+     * @param colonyName - Name of the colony
+     * @param processId - ID of the process to watch
+     * @param state - Target state to wait for (0=WAITING, 1=RUNNING, 2=SUCCESS, 3=FAILED)
+     * @param timeout - Timeout in seconds for the subscription
+     * @param onProcess - Callback when process reaches the target state
+     * @param onError - Callback for errors
+     * @param onClose - Callback when connection closes
+     * @returns WebSocket instance for cleanup
+     */
+    subscribeProcess(colonyName: string, processId: string, state: number, timeout: number, onProcess: (process: any) => void, onError: (error: Error) => void, onClose: () => void): WebSocket;
+}
+
+export { ColoniesClient, type ColoniesClientConfig, Crypto, type FunctionSpec, ProcessState, type RPCMessage, deriveId, generatePrivateKey, sign };