captify 0.1.15

package/dist/services/s3/interfaces/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./s3.interface";
+//# sourceMappingURL=index.d.ts.map

package/dist/services/s3/interfaces/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../lib/services/s3/interfaces/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/services/s3/interfaces/index.js

@@ -0,0 +1,2 @@
+export * from "./s3.interface";
+//# sourceMappingURL=index.js.map

package/dist/services/s3/interfaces/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../lib/services/s3/interfaces/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/services/s3/interfaces/s3.interface.d.ts

@@ -0,0 +1,255 @@
+import { Logger } from "../../logger";
+import { UserAwsCredentials } from "../../shared";
+import { ObjectCannedACL, ObjectStorageClass, S3Client, ServerSideEncryption } from "@aws-sdk/client-s3";
+export interface S3Config {
+    region: string;
+    bucketName: string;
+    /**
+     * Admin credentials for service operations
+     * Use when performing operations with service account (not user-specific)
+     */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+    endpoint?: string;
+    forcePathStyle?: boolean;
+}
+export interface S3ServiceDeps {
+    logger?: Logger;
+    s3Config: S3Config;
+    client?: S3Client;
+}
+export interface S3UploadFileParams {
+    key: string;
+    body: Buffer | Uint8Array | string | ReadableStream;
+    contentType?: string;
+    metadata?: Record<string, string>;
+    storageClass?: ObjectStorageClass;
+    serverSideEncryption?: ServerSideEncryption;
+    acl?: ObjectCannedACL;
+    cacheControl?: string;
+    expires?: Date;
+    /**
+     * User-specific AWS credentials for governance compliance
+     * When provided, the operation uses these credentials instead of service account
+     * This enables IAM-based access control per user
+     */
+    userCredentials?: UserAwsCredentials;
+}
+export interface S3DownloadFileParams {
+    key: string;
+    versionId?: string;
+    /** User-specific AWS credentials for governance compliance */
+    userCredentials?: UserAwsCredentials;
+    /**
+     * Skip the file size check for in-memory downloads
+     * WARNING: Only use if you're certain the file is small enough
+     */
+    skipSizeCheck?: boolean;
+}
+export interface S3DeleteFileParams {
+    key: string;
+    versionId?: string;
+    /** User-specific AWS credentials for governance compliance */
+    userCredentials?: UserAwsCredentials;
+}
+export interface S3ListFilesParams {
+    prefix?: string;
+    delimiter?: string;
+    maxKeys?: number;
+    continuationToken?: string;
+    startAfter?: string;
+    /** User-specific AWS credentials for governance compliance */
+    userCredentials?: UserAwsCredentials;
+}
+export interface S3FileObject {
+    key: string;
+    size?: number;
+    lastModified?: Date;
+    etag?: string;
+    storageClass?: string;
+    owner?: {
+        id?: string;
+        displayName?: string;
+    };
+    versionId?: string;
+}
+export interface S3ListFilesResult {
+    objects: S3FileObject[];
+    isTruncated: boolean;
+    nextContinuationToken?: string;
+    commonPrefixes?: string[];
+}
+export interface S3SignedUrlParams {
+    key: string;
+    operation: "getObject" | "putObject";
+    expiresIn?: number;
+    contentType?: string;
+    userCredentials?: UserAwsCredentials;
+    responseContentDisposition?: string;
+    /**
+     * Byte range for partial content downloads (resumable downloads)
+     * Format: "bytes=start-end" (e.g., "bytes=0-1023" for first 1KB)
+     */
+    range?: string;
+}
+export interface S3CopyFileParams {
+    sourceKey: string;
+    destinationKey: string;
+    sourceBucket?: string;
+    metadata?: Record<string, string>;
+    metadataDirective?: "COPY" | "REPLACE";
+    storageClass?: ObjectStorageClass;
+    serverSideEncryption?: ServerSideEncryption;
+    acl?: ObjectCannedACL;
+}
+export interface S3HeadObjectParams {
+    key: string;
+    versionId?: string;
+    userCredentials?: UserAwsCredentials;
+}
+export interface S3HeadObjectResult {
+    contentLength?: number;
+    contentType?: string;
+    lastModified?: Date;
+    etag?: string;
+    metadata?: Record<string, string>;
+    storageClass?: string;
+    serverSideEncryption?: string;
+}
+export interface S3MultipartUploadParams extends S3UploadFileParams {
+    partSize?: number;
+    queueSize?: number;
+    onProgress?: (progress: {
+        loaded?: number;
+        total?: number;
+        part?: number;
+    }) => void;
+}
+export interface S3DownloadStreamParams extends S3DownloadFileParams {
+    range?: string;
+    /**
+     * Progress callback for tracking download progress
+     * Receives loaded bytes, total bytes, and percentage
+     */
+    onProgress?: (progress: {
+        loaded: number;
+        total: number;
+        percentage: number;
+    }) => void;
+}
+export interface S3BatchDeleteParams {
+    keys: string[];
+    quiet?: boolean;
+}
+export interface S3BatchDeleteResult {
+    deleted: string[];
+    errors: Array<{
+        key: string;
+        code?: string;
+        message?: string;
+    }>;
+}
+export interface S3Tag {
+    key: string;
+    value: string;
+}
+export interface S3CreateMultipartUploadParams {
+    key: string;
+    contentType?: string;
+    metadata?: Record<string, string>;
+    serverSideEncryption?: ServerSideEncryption;
+    userCredentials?: UserAwsCredentials;
+}
+export interface S3CreateMultipartUploadResult {
+    uploadId: string;
+    key: string;
+    bucket: string;
+}
+export interface S3GetUploadPartUrlParams {
+    key: string;
+    uploadId: string;
+    partNumber: number;
+    expiresIn?: number;
+    userCredentials?: UserAwsCredentials;
+}
+export interface S3CompleteMultipartUploadParams {
+    key: string;
+    uploadId: string;
+    parts: Array<{
+        partNumber: number;
+        etag: string;
+    }>;
+    userCredentials?: UserAwsCredentials;
+}
+export interface S3CompleteMultipartUploadResult {
+    key: string;
+    bucket: string;
+    etag: string;
+    location?: string;
+}
+export interface S3AbortMultipartUploadParams {
+    key: string;
+    uploadId: string;
+    userCredentials?: UserAwsCredentials;
+}
+export interface S3ChunkedDownloadParams extends S3DownloadFileParams {
+    /**
+     * Size of each chunk in bytes
+     * Default: 10MB (10 * 1024 * 1024)
+     * Recommended: 5MB - 50MB depending on network conditions
+     */
+    chunkSize?: number;
+    /**
+     * Progress callback for tracking download progress
+     * Called after each chunk is downloaded
+     */
+    onProgress?: (progress: {
+        loaded: number;
+        total: number;
+        percentage: number;
+    }) => void;
+    /**
+     * AbortSignal for cancellation support
+     * When aborted, in-flight requests will be cancelled and the generator will throw
+     */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Parameters for listing S3 buckets
+ */
+export interface S3ListBucketsParams {
+    /** User-specific AWS credentials for governance compliance */
+    userCredentials?: UserAwsCredentials;
+}
+/**
+ * Parameters for checking bucket access
+ */
+export interface S3CheckBucketAccessParams {
+    /** User-specific AWS credentials for governance compliance */
+    userCredentials?: UserAwsCredentials;
+}
+/**
+ * Represents an S3 bucket
+ */
+export interface S3Bucket {
+    /** The name of the bucket */
+    name: string;
+    /** Date the bucket was created */
+    creationDate?: Date;
+}
+/**
+ * Result of listing S3 buckets
+ */
+export interface S3ListBucketsResult {
+    /** List of buckets the user has access to */
+    buckets: S3Bucket[];
+    /** The owner of the buckets (account info) */
+    owner?: {
+        id?: string;
+        displayName?: string;
+    };
+}
+//# sourceMappingURL=s3.interface.d.ts.map

package/dist/services/s3/interfaces/s3.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.interface.d.ts","sourceRoot":"","sources":["../../../../lib/services/s3/interfaces/s3.interface.ts"],"names":[],"mappings":"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"}

package/dist/services/s3/interfaces/s3.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=s3.interface.js.map

package/dist/services/s3/interfaces/s3.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.interface.js","sourceRoot":"","sources":["../../../../lib/services/s3/interfaces/s3.interface.ts"],"names":[],"mappings":""}

package/dist/services/s3/services/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./s3-service.factory";
+export * from "./s3.service";
+export * from "./singleton";
+//# sourceMappingURL=index.d.ts.map

package/dist/services/s3/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../lib/services/s3/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/services/s3/services/index.js

@@ -0,0 +1,4 @@
+export * from "./s3-service.factory";
+export * from "./s3.service";
+export * from "./singleton";
+//# sourceMappingURL=index.js.map

package/dist/services/s3/services/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../lib/services/s3/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/services/s3/services/s3-service.factory.d.ts

@@ -0,0 +1,24 @@
+import { Logger } from "../../logger";
+import { S3Client } from "@aws-sdk/client-s3";
+import { S3Config } from "../interfaces";
+interface TemporaryS3Credentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+}
+export declare class S3ServiceFactory {
+    static createWithTemporaryCredentials(credentials: TemporaryS3Credentials, config: Partial<S3Config>, logger?: Logger): {
+        client: S3Client;
+        bucketName: string;
+        region: string;
+        logger: Logger;
+    };
+    static createWithEnvCredentials(config: Partial<S3Config>, logger?: Logger): {
+        client: S3Client;
+        bucketName: string;
+        region: string;
+        logger: Logger;
+    };
+}
+export {};
+//# sourceMappingURL=s3-service.factory.d.ts.map

package/dist/services/s3/services/s3-service.factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-service.factory.d.ts","sourceRoot":"","sources":["../../../../lib/services/s3/services/s3-service.factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAiB,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,UAAU,sBAAsB;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,gBAAgB;IAC3B,MAAM,CAAC,8BAA8B,CACnC,WAAW,EAAE,sBAAsB,EACnC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,EACzB,MAAM,CAAC,EAAE,MAAM;;;;;;IA0CjB,MAAM,CAAC,wBAAwB,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM;;;;;;CAuC3E"}

package/dist/services/s3/services/s3-service.factory.js

@@ -0,0 +1,77 @@
+import { LoggerFactory } from "../../logger";
+import { S3Client } from "@aws-sdk/client-s3";
+export class S3ServiceFactory {
+    static createWithTemporaryCredentials(credentials, config, logger) {
+        if (!config.bucketName) {
+            throw new Error("S3 bucket name is required");
+        }
+        if (!config.region) {
+            throw new Error("S3 region is required");
+        }
+        const finalLogger = logger ||
+            LoggerFactory.createLogger({
+                serviceName: "S3-Temp",
+                userContext: {
+                    userId: "system",
+                    email: "system@captify.com",
+                    name: "System Service Account",
+                    roles: ["service"],
+                    metadata: {
+                        isSystemUser: true,
+                        note: "Temporary credentials factory - user context should be provided by caller",
+                    },
+                },
+            });
+        const s3Client = new S3Client({
+            region: config.region,
+            credentials: {
+                accessKeyId: credentials.accessKeyId,
+                secretAccessKey: credentials.secretAccessKey,
+                sessionToken: credentials.sessionToken,
+            },
+        });
+        return {
+            client: s3Client,
+            bucketName: config.bucketName,
+            region: config.region,
+            logger: finalLogger,
+        };
+    }
+    static createWithEnvCredentials(config, logger) {
+        var _a, _b;
+        if (!config.bucketName) {
+            throw new Error("S3 bucket name is required");
+        }
+        if (!config.region) {
+            throw new Error("S3 region is required");
+        }
+        const finalLogger = logger ||
+            LoggerFactory.createLogger({
+                serviceName: "S3-Env",
+                userContext: {
+                    userId: "system",
+                    email: "system@captify.com",
+                    name: "System Service Account",
+                    roles: ["service"],
+                    metadata: {
+                        isSystemUser: true,
+                        note: "Environment credentials factory - user context should be provided by caller",
+                    },
+                },
+            });
+        const s3Client = new S3Client({
+            region: config.region,
+            credentials: {
+                accessKeyId: (_a = process.env.AWS_ACCESS_KEY_ID) !== null && _a !== void 0 ? _a : "",
+                secretAccessKey: (_b = process.env.AWS_SECRET_ACCESS_KEY) !== null && _b !== void 0 ? _b : "",
+            },
+        });
+        return {
+            client: s3Client,
+            bucketName: config.bucketName,
+            region: config.region,
+            logger: finalLogger,
+        };
+    }
+}
+//# sourceMappingURL=s3-service.factory.js.map

package/dist/services/s3/services/s3-service.factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-service.factory.js","sourceRoot":"","sources":["../../../../lib/services/s3/services/s3-service.factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAS9C,MAAM,OAAO,gBAAgB;IAC3B,MAAM,CAAC,8BAA8B,CACnC,WAAmC,EACnC,MAAyB,EACzB,MAAe;QAEf,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAChD,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QAC3C,CAAC;QAED,MAAM,WAAW,GACf,MAAM;YACN,aAAa,CAAC,YAAY,CAAC;gBACzB,WAAW,EAAE,SAAS;gBACtB,WAAW,EAAE;oBACX,MAAM,EAAE,QAAQ;oBAChB,KAAK,EAAE,oBAAoB;oBAC3B,IAAI,EAAE,wBAAwB;oBAC9B,KAAK,EAAE,CAAC,SAAS,CAAC;oBAClB,QAAQ,EAAE;wBACR,YAAY,EAAE,IAAI;wBAClB,IAAI,EAAE,2EAA2E;qBAClF;iBACF;aACF,CAAC,CAAC;QAEL,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC;YAC5B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,WAAW,EAAE;gBACX,WAAW,EAAE,WAAW,CAAC,WAAW;gBACpC,eAAe,EAAE,WAAW,CAAC,eAAe;gBAC5C,YAAY,EAAE,WAAW,CAAC,YAAY;aACvC;SACF,CAAC,CAAC;QAEH,OAAO;YACL,MAAM,EAAE,QAAQ;YAChB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,WAAW;SACpB,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,wBAAwB,CAAC,MAAyB,EAAE,MAAe;;QACxE,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAChD,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QAC3C,CAAC;QAED,MAAM,WAAW,GACf,MAAM;YACN,aAAa,CAAC,YAAY,CAAC;gBACzB,WAAW,EAAE,QAAQ;gBACrB,WAAW,EAAE;oBACX,MAAM,EAAE,QAAQ;oBAChB,KAAK,EAAE,oBAAoB;oBAC3B,IAAI,EAAE,wBAAwB;oBAC9B,KAAK,EAAE,CAAC,SAAS,CAAC;oBAClB,QAAQ,EAAE;wBACR,YAAY,EAAE,IAAI;wBAClB,IAAI,EAAE,6EAA6E;qBACpF;iBACF;aACF,CAAC,CAAC;QAEL,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC;YAC5B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,WAAW,EAAE;gBACX,WAAW,EAAE,MAAA,OAAO,CAAC,GAAG,CAAC,iBAAiB,mCAAI,EAAE;gBAChD,eAAe,EAAE,MAAA,OAAO,CAAC,GAAG,CAAC,qBAAqB,mCAAI,EAAE;aACzD;SACF,CAAC,CAAC;QAEH,OAAO;YACL,MAAM,EAAE,QAAQ;YAChB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,WAAW;SACpB,CAAC;IACJ,CAAC;CACF"}

package/dist/services/s3/services/s3.service.d.ts

@@ -0,0 +1,193 @@
+import { Logger } from "../../logger";
+import { BaseAwsError, BaseAwsService } from "../../shared";
+import { Readable } from "stream";
+import { S3AbortMultipartUploadParams, S3BatchDeleteParams, S3BatchDeleteResult, S3CheckBucketAccessParams, S3ChunkedDownloadParams, S3CompleteMultipartUploadParams, S3CompleteMultipartUploadResult, S3Config, S3CopyFileParams, S3CreateMultipartUploadParams, S3CreateMultipartUploadResult, S3DeleteFileParams, S3DownloadFileParams, S3DownloadStreamParams, S3GetUploadPartUrlParams, S3HeadObjectParams, S3HeadObjectResult, S3ListBucketsParams, S3ListBucketsResult, S3ListFilesParams, S3ListFilesResult, S3MultipartUploadParams, S3SignedUrlParams, S3Tag, S3UploadFileParams } from "../interfaces";
+export declare class S3Service extends BaseAwsService {
+    private readonly s3;
+    private readonly bucketName;
+    private readonly config;
+    private constructor();
+    /**
+     * Get S3 client with user-specific credentials for governance compliance
+     * If userCredentials are provided, creates a new client with those credentials
+     * Otherwise, returns the default service account client
+     */
+    private getClientForOperation;
+    static create(config: Partial<S3Config>, logger?: Logger): S3Service;
+    static loadEnvConfig(bucketName?: string): Partial<S3Config>;
+    protected classifyError(err: unknown): BaseAwsError;
+    uploadFile(params: S3UploadFileParams): Promise<void>;
+    /**
+     * Download a file from S3 into memory
+     * WARNING: This method loads the entire file into memory. For files larger than 50MB,
+     * use downloadFileStream() or generateSignedUrl() instead.
+     *
+     * @param params - Download parameters including key and optional version ID
+     * @returns Promise<Uint8Array> - File contents as byte array
+     * @throws Error if file is larger than MAX_IN_MEMORY_DOWNLOAD_SIZE (50MB) unless skipSizeCheck is true
+     */
+    downloadFile(params: S3DownloadFileParams): Promise<Uint8Array>;
+    deleteFile(params: S3DeleteFileParams): Promise<void>;
+    listFiles(params?: S3ListFilesParams): Promise<S3ListFilesResult>;
+    /**
+     * List all S3 buckets accessible to the user
+     * Uses ListBucketsCommand to retrieve all buckets in the AWS account
+     * that the credentials have access to
+     *
+     * @param params - Optional parameters including user credentials
+     * @returns Promise<S3ListBucketsResult> - List of buckets with metadata
+     */
+    listBuckets(params?: S3ListBucketsParams): Promise<S3ListBucketsResult>;
+    /**
+     * Check if the user has access to this bucket.
+     * Uses a lightweight ListObjectsV2 with MaxKeys=0 to verify access without fetching data.
+     *
+     * @param params - Optional parameters including user credentials
+     * @returns Promise<boolean> - true if user has access, false otherwise
+     */
+    checkBucketAccess(params?: S3CheckBucketAccessParams): Promise<boolean>;
+    copyFile(params: S3CopyFileParams): Promise<void>;
+    headObject(params: S3HeadObjectParams): Promise<S3HeadObjectResult>;
+    /**
+     * Generate a pre-signed URL for temporary access to S3 objects
+     * Supports range requests for resumable downloads
+     *
+     * @param params - Parameters including key, operation, expiry, and optional range
+     * @returns Promise<string> - Pre-signed URL
+     *
+     * @example
+     * ```typescript
+     * // Regular download URL
+     * const url = await service.generateSignedUrl({
+     *   key: 'file.pdf',
+     *   operation: 'getObject',
+     *   expiresIn: 300, // 5 minutes
+     *   responseContentDisposition: 'attachment; filename="document.pdf"'
+     * });
+     *
+     * // Resumable download with range
+     * const partialUrl = await service.generateSignedUrl({
+     *   key: 'large-file.bin',
+     *   operation: 'getObject',
+     *   range: 'bytes=0-1048575', // First 1MB
+     *   expiresIn: 3600
+     * });
+     * ```
+     */
+    generateSignedUrl(params: S3SignedUrlParams): Promise<string>;
+    /**
+     * Initiate a multipart upload for client-side chunked uploads
+     * Returns an uploadId that must be used for all subsequent part uploads
+     */
+    createMultipartUpload(params: S3CreateMultipartUploadParams): Promise<S3CreateMultipartUploadResult>;
+    /**
+     * Generate a presigned URL for uploading a specific part of a multipart upload
+     * Each part must be at least 5MB (except the last part)
+     */
+    getUploadPartUrl(params: S3GetUploadPartUrlParams): Promise<string>;
+    /**
+     * Complete a multipart upload by combining all uploaded parts
+     * Parts must be provided in order with their ETags
+     */
+    completeMultipartUpload(params: S3CompleteMultipartUploadParams): Promise<S3CompleteMultipartUploadResult>;
+    /**
+     * Abort a multipart upload and clean up any uploaded parts
+     * Should be called when an upload fails or is cancelled
+     */
+    abortMultipartUpload(params: S3AbortMultipartUploadParams): Promise<void>;
+    /**
+     * Upload large files using multipart upload with progress tracking
+     * Automatically handles files with parallel part uploads for better performance
+     * Recommended for files larger than 100MB
+     */
+    uploadLargeFile(params: S3MultipartUploadParams): Promise<void>;
+    /**
+     * Download file as a stream for large files or partial downloads
+     * Returns a readable stream instead of loading into memory
+     * Useful for large files or when you want to pipe the download
+     * Supports progress tracking for monitoring download progress
+     *
+     * @param params - Download parameters including key, range, and optional progress callback
+     * @returns Promise<Readable> - Readable stream of file contents
+     */
+    downloadFileStream(params: S3DownloadStreamParams): Promise<Readable>;
+    /**
+     * Download large files in chunks with progress tracking
+     * Returns an async generator that yields chunks
+     * Useful for very large files that shouldn't be loaded into memory all at once
+     *
+     * Supports AbortSignal for proper cancellation of in-flight requests when the
+     * caller abandons iteration early.
+     *
+     * @example
+     * ```typescript
+     * const controller = new AbortController();
+     * const chunks = [];
+     * try {
+     *   for await (const chunk of service.downloadFileInChunks({
+     *     key: 'large-file.bin',
+     *     chunkSize: 10 * 1024 * 1024, // 10MB chunks
+     *     onProgress: (progress) => console.log(`${progress.percentage}%`),
+     *     abortSignal: controller.signal
+     *   })) {
+     *     chunks.push(chunk);
+     *     if (shouldCancel) {
+     *       controller.abort();
+     *       break;
+     *     }
+     *   }
+     * } catch (err) {
+     *   if (err.name === 'AbortError') {
+     *     console.log('Download cancelled');
+     *   }
+     * }
+     * const fullFile = Buffer.concat(chunks.map(c => Buffer.from(c)));
+     * ```
+     *
+     * @param params - Download parameters including key, chunk size, progress callback, and abort signal
+     * @returns AsyncGenerator<Uint8Array> - Yields file chunks
+     */
+    downloadFileInChunks(params: S3ChunkedDownloadParams): AsyncGenerator<Uint8Array, void, unknown>;
+    /**
+     * Delete multiple objects in a single request (up to 1000 objects)
+     * More efficient than individual delete operations
+     */
+    batchDeleteFiles(params: S3BatchDeleteParams): Promise<S3BatchDeleteResult>;
+    /**
+     * Add or update tags on an S3 object
+     * Tags can be used for organization, access control, and cost allocation
+     */
+    tagObject(key: string, tags: S3Tag[]): Promise<void>;
+    /**
+     * Get tags for an S3 object
+     */
+    getObjectTags(key: string): Promise<S3Tag[]>;
+    /**
+     * List all files with automatic pagination using async generator
+     * Usage: for await (const batch of service.listAllFiles({ prefix: 'photos/' })) { ... }
+     */
+    listAllFiles(params?: Omit<S3ListFilesParams, "continuationToken">): AsyncGenerator<S3ListFilesResult, void, unknown>;
+    /**
+     * Cleanup and destroy the S3Client
+     * Call this when shutting down the service to free resources
+     */
+    destroy(): Promise<void>;
+    protected onMetric(name: string, dims: Record<string, unknown>): void;
+    getBucketName(): string;
+    /**
+     * Get the public URL for an S3 object.
+     * Respects custom endpoint and forcePathStyle settings.
+     *
+     * @param key The S3 object key
+     * @returns The full URL to the object
+     */
+    getObjectUrl(key: string): string;
+    /**
+     * Get the URL prefix for S3 objects.
+     * Useful for matching URLs to check if they belong to this bucket.
+     *
+     * @returns The URL prefix (without trailing slash)
+     */
+    getObjectUrlPrefix(): string;
+}
+//# sourceMappingURL=s3.service.d.ts.map

package/dist/services/s3/services/s3.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.service.d.ts","sourceRoot":"","sources":["../../../../lib/services/s3/services/s3.service.ts"],"names":[],"mappings":"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"}