/**
 * Copyright (c) 2025 Elara AI Pty Ltd
 * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
 */
/**
 * S3 platform functions for East Node IO.
 *
 * Provides S3 and S3-compatible object storage operations for East programs,
 * including upload, download, delete, list, and presigned URL generation.
 *
 * @packageDocumentation
 */
import { BlobType, StringType, IntegerType, NullType, OptionType } from "@elaraai/east";
import type { PlatformFunction } from "@elaraai/east/internal";
/**
 * Uploads an object to S3.
 *
 * Uploads binary data to an S3 bucket with the specified key (path).
 * Overwrites existing objects with the same key.
 *
 * This is a platform function for the East language, enabling S3 object storage
 * operations in East programs running on Node.js.
 *
 * @param config - S3 configuration
 * @param key - Object key (path) in the bucket
 * @param data - Binary data to upload
 * @returns Null on success
 *
 * @throws {EastError} When upload fails due to:
 * - Invalid bucket name (location: "s3_put_object")
 * - Authentication failure (location: "s3_put_object")
 * - Network errors (location: "s3_put_object")
 * - Permission denied (location: "s3_put_object")
 *
 * @example
 * ```ts
 * import { East, StringType, BlobType } from "@elaraai/east";
 * import { Storage } from "@elaraai/east-node-io";
 *
 * const uploadFile = East.function([StringType, BlobType], StringType, ($, filename, data) => {
 *     const config = $.let({
 *         region: "us-east-1",
 *         bucket: "my-bucket",
 *         accessKeyId: East.some("AKIAIOSFODNN7EXAMPLE"),
 *         secretAccessKey: East.some("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"),
 *         endpoint: East.none(),
 *     });
 *
 *     // Upload the file
 *     $(Storage.S3.putObject(config, filename, data));
 *
 *     // Generate presigned URL for sharing
 *     return Storage.S3.presignUrl(config, filename, 3600n);
 * });
 *
 * const compiled = East.compileAsync(uploadFile.toIR(), Storage.S3.Implementation);
 * const url = await compiled("report.pdf", pdfBlob);
 * ```
 *
 * @remarks
 * - Supports S3 and S3-compatible services (MinIO, DigitalOcean Spaces, etc.)
 * - Uses AWS SDK v3 for S3 operations
 * - All operations are asynchronous (use East.compileAsync)
 */
export declare const s3_put_object: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
    readonly region: StringType;
    readonly bucket: StringType;
    readonly accessKeyId: OptionType<StringType>;
    readonly secretAccessKey: OptionType<StringType>;
    readonly endpoint: OptionType<StringType>;
}>, StringType, BlobType], NullType>;
/**
 * Downloads an object from S3.
 *
 * Retrieves binary data from an S3 bucket by key (path).
 * Returns the object data as a Blob (Uint8Array).
 *
 * This is a platform function for the East language, enabling S3 object storage
 * operations in East programs running on Node.js.
 *
 * @param config - S3 configuration
 * @param key - Object key (path) in the bucket
 * @returns Binary data as Blob
 *
 * @throws {EastError} When download fails due to:
 * - Object not found (location: "s3_get_object")
 * - Invalid bucket name (location: "s3_get_object")
 * - Authentication failure (location: "s3_get_object")
 * - Network errors (location: "s3_get_object")
 * - Permission denied (location: "s3_get_object")
 *
 * @example
 * ```ts
 * import { East, StringType, BlobType } from "@elaraai/east";
 * import { Storage } from "@elaraai/east-node-io";
 *
 * const downloadFile = East.function([StringType], BlobType, ($, filename) => {
 *     const config = $.let({
 *         region: "us-east-1",
 *         bucket: "my-bucket",
 *         accessKeyId: East.none(),
 *         secretAccessKey: East.none(),
 *         endpoint: East.none(),
 *     });
 *
 *     return Storage.S3.getObject(config, filename);
 * });
 *
 * const compiled = East.compileAsync(downloadFile.toIR(), Storage.S3.Implementation);
 * const pdfData = await compiled("report.pdf");  // Returns Uint8Array
 * ```
 *
 * @remarks
 * - Returns Uint8Array (BlobType) containing raw binary data
 * - Use decodeUtf8() to convert text files to strings
 * - Streams large objects automatically
 */
export declare const s3_get_object: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
    readonly region: StringType;
    readonly bucket: StringType;
    readonly accessKeyId: OptionType<StringType>;
    readonly secretAccessKey: OptionType<StringType>;
    readonly endpoint: OptionType<StringType>;
}>, StringType], BlobType>;
/**
 * Retrieves object metadata from S3 without downloading the file.
 *
 * Gets metadata for an S3 object including size, ETag (hash), last modified time,
 * and content type. This is useful for checking if a file has changed without
 * downloading it by comparing ETags.
 *
 * This is a platform function for the East language, enabling S3 object storage
 * operations in East programs running on Node.js.
 *
 * @param config - S3 configuration
 * @param key - Object key (path) in the bucket
 * @returns Object metadata including ETag, size, and timestamps
 *
 * @throws {EastError} When metadata retrieval fails due to:
 * - Object not found (location: "s3_head_object")
 * - Invalid bucket name (location: "s3_head_object")
 * - Authentication failure (location: "s3_head_object")
 * - Network errors (location: "s3_head_object")
 * - Permission denied (location: "s3_head_object")
 *
 * @example
 * ```ts
 * import { East, StringType } from "@elaraai/east";
 * import { Storage } from "@elaraai/east-node-io";
 *
 * const checkFileChanged = East.function([StringType, StringType], BooleanType, ($, filename, localEtag) => {
 *     const config = $.let({
 *         region: "us-east-1",
 *         bucket: "my-bucket",
 *         accessKeyId: East.none(),
 *         secretAccessKey: East.none(),
 *         endpoint: East.none(),
 *     });
 *
 *     const metadata = $.let(Storage.S3.headObject(config, filename));
 *
 *     return $.match(metadata.etag, {
 *         some: ($, remoteEtag) => remoteEtag.notEqual(localEtag),
 *         none: ($) => East.value(true), // File changed if no ETag available
 *     });
 * });
 *
 * const compiled = East.compileAsync(checkFileChanged.toIR(), Storage.S3.Implementation);
 * const changed = await compiled("report.pdf", '"abc123def456"');  // ETags include quotes
 * if (changed) {
 *     // Download the file since it changed
 * }
 * ```
 *
 * @remarks
 * - ETag is typically an MD5 hash (for simple uploads) or composite hash (for multipart uploads)
 * - ETags include surrounding quotes (e.g., '"abc123"')
 * - Much faster than downloading the entire file
 * - Use this to implement efficient sync/caching logic
 */
export declare const s3_head_object: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
    readonly region: StringType;
    readonly bucket: StringType;
    readonly accessKeyId: OptionType<StringType>;
    readonly secretAccessKey: OptionType<StringType>;
    readonly endpoint: OptionType<StringType>;
}>, StringType], import("@elaraai/east").StructType<{
    readonly key: StringType;
    readonly size: IntegerType;
    readonly lastModified: import("@elaraai/east").DateTimeType;
    readonly contentType: OptionType<StringType>;
    readonly etag: OptionType<StringType>;
}>>;
/**
 * Deletes an object from S3.
 *
 * Removes an object from an S3 bucket by key (path).
 * Succeeds even if the object doesn't exist (idempotent).
 *
 * This is a platform function for the East language, enabling S3 object storage
 * operations in East programs running on Node.js.
 *
 * @param config - S3 configuration
 * @param key - Object key (path) to delete
 * @returns Null on success
 *
 * @throws {EastError} When deletion fails due to:
 * - Invalid bucket name (location: "s3_delete_object")
 * - Authentication failure (location: "s3_delete_object")
 * - Network errors (location: "s3_delete_object")
 * - Permission denied (location: "s3_delete_object")
 *
 * @example
 * ```ts
 * import { East, StringType, NullType } from "@elaraai/east";
 * import { Storage } from "@elaraai/east-node-io";
 *
 * const deleteFile = East.function([StringType], NullType, ($, filename) => {
 *     const config = $.let({
 *         region: "us-east-1",
 *         bucket: "my-bucket",
 *         accessKeyId: East.none(),
 *         secretAccessKey: East.none(),
 *         endpoint: East.none(),
 *     });
 *
 *     return Storage.S3.deleteObject(config, filename);
 * });
 *
 * const compiled = East.compileAsync(deleteFile.toIR(), Storage.S3.Implementation);
 * await compiled("old-report.pdf");
 * ```
 *
 * @remarks
 * - Idempotent: succeeds even if object doesn't exist
 * - Does not delete versioned objects (only current version)
 */
export declare const s3_delete_object: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
    readonly region: StringType;
    readonly bucket: StringType;
    readonly accessKeyId: OptionType<StringType>;
    readonly secretAccessKey: OptionType<StringType>;
    readonly endpoint: OptionType<StringType>;
}>, StringType], NullType>;
/**
 * Lists objects in an S3 bucket with a prefix.
 *
 * Retrieves metadata for objects matching a prefix, with pagination support.
 * Returns up to `maxKeys` objects per request. Pass a continuation token
 * from a previous result to fetch the next page.
 *
 * This is a platform function for the East language, enabling S3 object storage
 * operations in East programs running on Node.js.
 *
 * @param config - S3 configuration
 * @param prefix - Prefix to filter objects (empty string for all objects)
 * @param maxKeys - Maximum number of objects to return (1-1000)
 * @param continuationToken - Continuation token from a previous list result for pagination (None for first page)
 * @returns List result with objects and pagination info
 *
 * @throws {EastError} When listing fails due to:
 * - Invalid bucket name (location: "s3_list_objects")
 * - Authentication failure (location: "s3_list_objects")
 * - Network errors (location: "s3_list_objects")
 * - Permission denied (location: "s3_list_objects")
 * - Invalid maxKeys value (location: "s3_list_objects")
 *
 * @example
 * ```ts
 * import { East, StringType, ArrayType } from "@elaraai/east";
 * import { Storage, S3ObjectMetadataType } from "@elaraai/east-node-io";
 *
 * const listReports = East.function([], ArrayType(S3ObjectMetadataType), ($) => {
 *     const config = $.let({
 *         region: "us-east-1",
 *         bucket: "my-bucket",
 *         accessKeyId: East.none(),
 *         secretAccessKey: East.none(),
 *         endpoint: East.none(),
 *     });
 *
 *     // First page
 *     const result = $.let(Storage.S3.listObjects(config, "reports/", 100n, East.none()));
 *
 *     // Next page using continuation token
 *     const page2 = $.let(Storage.S3.listObjects(config, "reports/", 100n, result.continuationToken));
 *     return page2.objects;
 * });
 *
 * const compiled = East.compileAsync(listReports.toIR(), Storage.S3.Implementation);
 * const reports = await compiled();
 * ```
 *
 * @remarks
 * - Returns objects sorted by key (lexicographically)
 * - Pass the `continuationToken` from the result to fetch the next page
 * - When `isTruncated` is false, there are no more pages
 * - maxKeys is clamped to 1-1000 range
 */
export declare const s3_list_objects: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
    readonly region: StringType;
    readonly bucket: StringType;
    readonly accessKeyId: OptionType<StringType>;
    readonly secretAccessKey: OptionType<StringType>;
    readonly endpoint: OptionType<StringType>;
}>, StringType, IntegerType, OptionType<StringType>], import("@elaraai/east").StructType<{
    readonly objects: import("@elaraai/east").ArrayType<import("@elaraai/east").StructType<{
        readonly key: StringType;
        readonly size: IntegerType;
        readonly lastModified: import("@elaraai/east").DateTimeType;
        readonly contentType: OptionType<StringType>;
        readonly etag: OptionType<StringType>;
    }>>;
    readonly isTruncated: import("@elaraai/east").BooleanType;
    readonly continuationToken: OptionType<StringType>;
}>>;
/**
 * Generates a presigned URL for temporary access to an S3 object.
 *
 * Creates a signed URL that grants temporary access to an object without
 * requiring AWS credentials. Useful for sharing files or client-side uploads.
 *
 * This is a platform function for the East language, enabling S3 object storage
 * operations in East programs running on Node.js.
 *
 * @param config - S3 configuration
 * @param key - Object key (path) in the bucket
 * @param expiresIn - URL expiration time in seconds (1-604800)
 * @returns Presigned URL as string
 *
 * @throws {EastError} When URL generation fails due to:
 * - Invalid bucket name (location: "s3_presign_url")
 * - Invalid expiration time (location: "s3_presign_url")
 * - Missing credentials (location: "s3_presign_url")
 * - Network errors (location: "s3_presign_url")
 *
 * @example
 * ```ts
 * import { East, StringType } from "@elaraai/east";
 * import { Storage } from "@elaraai/east-node-io";
 *
 * const shareFile = East.function([StringType], StringType, ($, filename) => {
 *     const config = $.let({
 *         region: "us-east-1",
 *         bucket: "my-bucket",
 *         accessKeyId: East.some("AKIAIOSFODNN7EXAMPLE"),
 *         secretAccessKey: East.some("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"),
 *         endpoint: East.none(),
 *     });
 *
 *     // Generate URL valid for 1 hour
 *     return Storage.S3.presignUrl(config, filename, 3600n);
 * });
 *
 * const compiled = East.compileAsync(shareFile.toIR(), Storage.S3.Implementation);
 * const url = await compiled("report.pdf");
 * console.log(`Share this link: ${url}`);
 * ```
 *
 * @remarks
 * - URL expires after `expiresIn` seconds
 * - Requires credentials (cannot use default AWS credential chain)
 * - Works with S3-compatible services
 * - Maximum expiration: 7 days (604800 seconds)
 */
export declare const s3_presign_url: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
    readonly region: StringType;
    readonly bucket: StringType;
    readonly accessKeyId: OptionType<StringType>;
    readonly secretAccessKey: OptionType<StringType>;
    readonly endpoint: OptionType<StringType>;
}>, StringType, IntegerType], StringType>;
/**
 * Node.js implementation of S3 platform functions.
 *
 * Provides the runtime implementations for S3 operations using AWS SDK v3.
 * Pass this to East.compileAsync() to enable S3 functionality.
 */
export declare const S3Impl: PlatformFunction[];
//# sourceMappingURL=s3.d.ts.map