@elaraai/east-node-io 0.0.1-beta.1 → 0.0.1-beta.2

package/dist/transfer/sftp.d.ts

@@ -0,0 +1,333 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * SFTP platform functions for East Node IO.
+ *
+ * Provides SFTP (SSH File Transfer Protocol) operations for East programs,
+ * including upload, download, list, and delete operations.
+ *
+ * @packageDocumentation
+ */
+import { BlobType, ArrayType, NullType } from "@elaraai/east";
+import type { PlatformFunction } from "@elaraai/east/internal";
+import { StringType } from "./types.js";
+/**
+ * Connects to an SFTP server.
+ *
+ * Creates a connection to an SFTP server and returns an opaque handle
+ * for use in file transfer operations.
+ *
+ * This is a platform function for the East language, enabling SFTP file transfer
+ * operations in East programs running on Node.js.
+ *
+ * @param config - SFTP connection configuration
+ * @returns Connection handle (opaque string)
+ *
+ * @throws {EastError} When connection fails due to:
+ * - Invalid hostname or port (location: "sftp_connect")
+ * - Authentication failure (location: "sftp_connect")
+ * - Network errors (location: "sftp_connect")
+ * - SSH key errors (location: "sftp_connect")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, BlobType } from "@elaraai/east";
+ * import { Transfer } from "@elaraai/east-node-io";
+ *
+ * const uploadToSftp = East.function([StringType, BlobType], NullType, ($, filename, data) => {
+ *     const config = $.let({
+ *         host: "sftp.example.com",
+ *         port: 22n,
+ *         username: "user",
+ *         password: East.some("password"),
+ *         privateKey: East.none(),
+ *     });
+ *
+ *     const conn = $.let(Transfer.SFTP.connect(config));
+ *     $(Transfer.SFTP.put(conn, filename, data));
+ *     $(Transfer.SFTP.close(conn));
+ * });
+ *
+ * const compiled = East.compileAsync(uploadToSftp.toIR(), Transfer.SFTP.Implementation);
+ * await compiled("file.txt", fileData);
+ * ```
+ *
+ * @remarks
+ * - Supports password and private key authentication
+ * - Connection is maintained until explicitly closed
+ * - All operations are asynchronous (use East.compileAsync)
+ */
+export declare const sftp_connect: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
+    host: StringType;
+    port: import("@elaraai/east").IntegerType;
+    username: StringType;
+    password: import("@elaraai/east").OptionType<StringType>;
+    privateKey: import("@elaraai/east").OptionType<StringType>;
+}>], StringType>;
+/**
+ * Uploads a file to an SFTP server.
+ *
+ * Uploads binary data to the SFTP server at the specified remote path.
+ * Overwrites existing files with the same path.
+ *
+ * This is a platform function for the East language, enabling SFTP file transfer
+ * operations in East programs running on Node.js.
+ *
+ * @param handle - Connection handle from sftp_connect()
+ * @param remotePath - Remote file path on the SFTP server
+ * @param data - Binary data to upload
+ * @returns Null on success
+ *
+ * @throws {EastError} When upload fails due to:
+ * - Invalid connection handle (location: "sftp_put")
+ * - Permission denied (location: "sftp_put")
+ * - Invalid remote path (location: "sftp_put")
+ * - Network errors (location: "sftp_put")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, BlobType, NullType, variant } from "@elaraai/east";
+ * import { Transfer } from "@elaraai/east-node-io";
+ *
+ * const uploadFile = East.function([StringType, BlobType], NullType, ($, filename, data) => {
+ *     const config = $.let({
+ *         host: "sftp.example.com",
+ *         port: 22n,
+ *         username: "user",
+ *         password: variant('some', "password"),
+ *         privateKey: variant('none', null),
+ *     });
+ *     const conn = $.let(Transfer.SFTP.connect(config));
+ *     $(Transfer.SFTP.put(conn, `/uploads/${filename}`, data));
+ *     $(Transfer.SFTP.close(conn));
+ *     return $.return(null);
+ * });
+ *
+ * const compiled = East.compileAsync(uploadFile.toIR(), Transfer.SFTP.Implementation);
+ * await compiled("file.txt", fileData);
+ * ```
+ *
+ * @remarks
+ * - Creates parent directories if they don't exist
+ * - Overwrites existing files
+ * - Binary mode transfer
+ */
+export declare const sftp_put: import("@elaraai/east").AsyncPlatformDefinition<[StringType, StringType, BlobType], NullType>;
+/**
+ * Downloads a file from an SFTP server.
+ *
+ * Retrieves binary data from the SFTP server at the specified remote path.
+ * Returns the file data as a Blob (Uint8Array).
+ *
+ * This is a platform function for the East language, enabling SFTP file transfer
+ * operations in East programs running on Node.js.
+ *
+ * @param handle - Connection handle from sftp_connect()
+ * @param remotePath - Remote file path on the SFTP server
+ * @returns Binary data as Blob
+ *
+ * @throws {EastError} When download fails due to:
+ * - Invalid connection handle (location: "sftp_get")
+ * - File not found (location: "sftp_get")
+ * - Permission denied (location: "sftp_get")
+ * - Network errors (location: "sftp_get")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, BlobType, variant } from "@elaraai/east";
+ * import { Transfer } from "@elaraai/east-node-io";
+ *
+ * const downloadFile = East.function([StringType], BlobType, ($, filename) => {
+ *     const config = $.let({
+ *         host: "sftp.example.com",
+ *         port: 22n,
+ *         username: "user",
+ *         password: variant('some', "password"),
+ *         privateKey: variant('none', null),
+ *     });
+ *     const conn = $.let(Transfer.SFTP.connect(config));
+ *     const data = $.let(Transfer.SFTP.get(conn, `/downloads/${filename}`));
+ *     $(Transfer.SFTP.close(conn));
+ *     return $.return(data);
+ * });
+ *
+ * const compiled = East.compileAsync(downloadFile.toIR(), Transfer.SFTP.Implementation);
+ * const fileData = await compiled("file.txt");  // Returns Uint8Array
+ * ```
+ *
+ * @remarks
+ * - Binary mode transfer
+ * - Entire file is loaded into memory
+ */
+export declare const sftp_get: import("@elaraai/east").AsyncPlatformDefinition<[StringType, StringType], BlobType>;
+/**
+ * Lists files in an SFTP directory.
+ *
+ * Retrieves a list of files and directories at the specified remote path.
+ * Returns metadata for each file including name, size, and modification time.
+ *
+ * This is a platform function for the East language, enabling SFTP file transfer
+ * operations in East programs running on Node.js.
+ *
+ * @param handle - Connection handle from sftp_connect()
+ * @param remotePath - Remote directory path on the SFTP server
+ * @returns Array of file information metadata
+ *
+ * @throws {EastError} When listing fails due to:
+ * - Invalid connection handle (location: "sftp_list")
+ * - Directory not found (location: "sftp_list")
+ * - Permission denied (location: "sftp_list")
+ * - Network errors (location: "sftp_list")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, ArrayType, variant } from "@elaraai/east";
+ * import { Transfer } from "@elaraai/east-node-io";
+ *
+ * const listFiles = East.function([StringType], ArrayType(Transfer.SFTP.Types.FileInfo), ($, remotePath) => {
+ *     const config = $.let({
+ *         host: "sftp.example.com",
+ *         port: 22n,
+ *         username: "user",
+ *         password: variant('some', "password"),
+ *         privateKey: variant('none', null),
+ *     });
+ *     const conn = $.let(Transfer.SFTP.connect(config));
+ *     const files = $.let(Transfer.SFTP.list(conn, remotePath));
+ *     $(Transfer.SFTP.close(conn));
+ *     return $.return(files);
+ * });
+ *
+ * const compiled = East.compileAsync(listFiles.toIR(), Transfer.SFTP.Implementation);
+ * const uploads = await compiled("/uploads");  // [{name: "file.txt", size: 1024n, ...}, ...]
+ * ```
+ *
+ * @remarks
+ * - Returns both files and directories
+ * - Use isDirectory field to distinguish between files and directories
+ */
+export declare const sftp_list: import("@elaraai/east").AsyncPlatformDefinition<[StringType, StringType], ArrayType<import("@elaraai/east").StructType<{
+    name: StringType;
+    path: StringType;
+    size: import("@elaraai/east").IntegerType;
+    isDirectory: import("@elaraai/east").BooleanType;
+    modifiedTime: StringType;
+}>>>;
+/**
+ * Deletes a file from an SFTP server.
+ *
+ * Removes a file from the SFTP server at the specified remote path.
+ * Does not delete directories.
+ *
+ * This is a platform function for the East language, enabling SFTP file transfer
+ * operations in East programs running on Node.js.
+ *
+ * @param handle - Connection handle from sftp_connect()
+ * @param remotePath - Remote file path to delete
+ * @returns Null on success
+ *
+ * @throws {EastError} When deletion fails due to:
+ * - Invalid connection handle (location: "sftp_delete")
+ * - File not found (location: "sftp_delete")
+ * - Permission denied (location: "sftp_delete")
+ * - Network errors (location: "sftp_delete")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, NullType, variant } from "@elaraai/east";
+ * import { Transfer } from "@elaraai/east-node-io";
+ *
+ * const deleteFile = East.function([StringType], NullType, ($, filename) => {
+ *     const config = $.let({
+ *         host: "sftp.example.com",
+ *         port: 22n,
+ *         username: "user",
+ *         password: variant('some', "password"),
+ *         privateKey: variant('none', null),
+ *     });
+ *     const conn = $.let(Transfer.SFTP.connect(config));
+ *     $(Transfer.SFTP.delete(conn, `/uploads/${filename}`));
+ *     $(Transfer.SFTP.close(conn));
+ *     return $.return(null);
+ * });
+ *
+ * const compiled = East.compileAsync(deleteFile.toIR(), Transfer.SFTP.Implementation);
+ * await compiled("old-file.txt");
+ * ```
+ *
+ * @remarks
+ * - Only deletes files, not directories
+ * - Throws error if file doesn't exist
+ */
+export declare const sftp_delete: import("@elaraai/east").AsyncPlatformDefinition<[StringType, StringType], NullType>;
+/**
+ * Closes an SFTP connection.
+ *
+ * Closes the SFTP connection and releases all resources.
+ * The handle becomes invalid after this operation.
+ *
+ * @param handle - Connection handle from sftp_connect()
+ * @returns Null on success
+ *
+ * @throws {EastError} When handle is invalid (location: "sftp_close")
+ *
+ * @example
+ * ```ts
+ * import { East, NullType, variant } from "@elaraai/east";
+ * import { Transfer } from "@elaraai/east-node-io";
+ *
+ * const cleanup = East.function([], NullType, $ => {
+ *     const config = $.let({
+ *         host: "sftp.example.com",
+ *         port: 22n,
+ *         username: "user",
+ *         password: variant('some', "password"),
+ *         privateKey: variant('none', null),
+ *     });
+ *     const conn = $.let(Transfer.SFTP.connect(config));
+ *     // ... do work ...
+ *     $(Transfer.SFTP.close(conn));
+ *     return $.return(null);
+ * });
+ *
+ * const compiled = East.compileAsync(cleanup.toIR(), Transfer.SFTP.Implementation);
+ * await compiled();
+ * ```
+ */
+export declare const sftp_close: import("@elaraai/east").AsyncPlatformDefinition<[StringType], NullType>;
+/**
+ * Closes all SFTP connections.
+ *
+ * Closes all active SFTP connections and releases all resources.
+ * Useful for test cleanup to ensure all connections are closed.
+ *
+ * @returns Null on success
+ *
+ * @example
+ * ```ts
+ * import { East, NullType } from "@elaraai/east";
+ * import { Transfer } from "@elaraai/east-node-io";
+ *
+ * const cleanupAll = East.function([], NullType, $ => {
+ *     // ... test code that may have left connections open ...
+ *     $(Transfer.SFTP.closeAll());
+ *     return $.return(null);
+ * });
+ *
+ * const compiled = East.compileAsync(cleanupAll.toIR(), Transfer.SFTP.Implementation);
+ * await compiled();
+ * ```
+ *
+ * @internal
+ */
+export declare const sftp_close_all: import("@elaraai/east").AsyncPlatformDefinition<[], NullType>;
+/**
+ * Node.js implementation of SFTP platform functions.
+ *
+ * Provides the runtime implementations for SFTP operations using ssh2-sftp-client.
+ * Pass this to East.compileAsync() to enable SFTP functionality.
+ */
+export declare const SftpImpl: PlatformFunction[];
+//# sourceMappingURL=sftp.d.ts.map

package/dist/transfer/sftp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sftp.d.ts","sourceRoot":"","sources":["../../src/transfer/sftp.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAAQ,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK/D,OAAO,EAAwC,UAAU,EAAgB,MAAM,YAAY,CAAC;AAE5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,YAAY;;;;;;gBAA6E,CAAC;AAEvG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,QAAQ,+FAAyF,CAAC;AAE/G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,QAAQ,qFAA+E,CAAC;AAErG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,SAAS;;;;;;IAA+F,CAAC;AAEtH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,WAAW,qFAAkF,CAAC;AAE3G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,UAAU,yEAAqE,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,cAAc,+DAAqD,CAAC;AAEjF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,gBAAgB,EAuItC,CAAC"}