@beespoke/micro-server-minio 0.0.0-stage → 2.0.5

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @beespoke/micro-server-minio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MinIO object storage, uploads, multipart sessions, downloads, and cleanup.
+
+Supports Node 24+ and Bun 1.3.14+.
+
+## Install
+
+```sh
+npm install @beespoke/micro-server @beespoke/micro-server-minio
+```
+
+Use `bun add` in place of `npm install` for Bun projects.
+
+## Configure the plugin
+
+```ts
+import { defineConfig } from '@beespoke/micro-server';
+
+export default defineConfig({
+    plugins: ['@beespoke/micro-server-minio'],
+    pluginOptions: {
+        '@beespoke/micro-server-minio': {
+            host: process.env.MINIO_HOST!,
+            port: Number(process.env.MINIO_PORT || 9000),
+            useSSL: false,
+            accessKey: process.env.MINIO_ACCESS_KEY!,
+            secretKey: process.env.MINIO_SECRET_KEY!,
+        },
+    },
+});
+```
+
+Requires a reachable MinIO server. `host` is a hostname, not a URL. Choose `useSSL` and `port` to match your server. Optional `region` selects the storage region. Buckets are supplied to storage operations, not to plugin configuration.
+
+## Storage API
+
+The root exports `Uploader` and upload/session types. After bootstrap, use `Uploader.upload(bucket, directory, fileOrFiles)`, `Uploader.delete(bucket, objectName)`, and the multipart methods `initiateUpload`, `uploadChunk`, and `completeUpload`. `streamDownload` writes a download to an HTTP response. Storage input types are exported for application adapters.
+
+For direct initialization, use `await Uploader.init({ minioHost, minioPort, minioUseSSL, minioAccessKey, minioSecretKey })` and `await Uploader.close()`. These direct option names differ from the shorter plugin option names above. Shutdown drains tracked operations and aborts unfinished multipart sessions.
+
+## Start the application
+
+Save the configuration as `micro-server.config.ts` next to your application's `package.json`, then create `index.ts`:
+
+```ts
+import { ApplicationServer } from '@beespoke/micro-server';
+
+await ApplicationServer.bootstrap();
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+    process.once(signal, () => {
+        void ApplicationServer.close().catch(error => {
+            console.error(error);
+            process.exitCode = 1;
+        });
+    });
+}
+```
+
+Run `bun index.ts` or `node --env-file-if-exists=.env index.ts`. Node requires ESM (`"type": "module"` in package.json). When using Bun, load configuration secrets from the application environment or its `.env` file.
+
+## TypeScript and lifecycle
+
+Add this type-only import to an application-owned `plugin-types.d.ts` for configuration autocomplete:
+
+```ts
+import type {} from '@beespoke/micro-server-minio/plugin';
+```
+
+Core validates plugin options before setup and owns cleanup after successful startup or startup failure. Await `ApplicationServer.bootstrap()` before using the configured client, and call `ApplicationServer.close()` during application shutdown. Importing the package does not open a connection. Relative plugin paths resolve from the selected configuration file's directory.
+
+The root export can also be used without HTTP core. In that case, explicitly initialize and close the client. The `/plugin` entry is the integration adapter for `@beespoke/micro-server`.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Uploader } from './utils/Uploader.js';
+export type { MinioOptions, ApplicationOptionType } from './types/MinioOptions.js';
+export type { UploadedFile, UploadedFileType, InitUpload, UploadPartConfig, UploadSession, UploadChunk, CompleteUploadResult, UploadTypes, UploadPart } from './types/UploadedFileType.js';

package/dist/index.js

@@ -0,0 +1,384 @@
+// src/utils/Uploader.ts
+import { Agent as HttpAgent } from "node:http";
+import { Agent as HttpsAgent } from "node:https";
+import { finished } from "node:stream";
+
+// src/support.ts
+var consoleLogger = {
+  info: (...args) => console.info(...args),
+  warn: (...args) => console.warn(...args),
+  error: (...args) => console.error(...args),
+  debug: (...args) => console.debug(...args)
+};
+
+// src/utils/Uploader.ts
+import * as minio from "minio";
+
+// src/utils/multipart.ts
+async function readAsString(response) {
+  const chunks = [];
+  for await (const chunk of response)
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  return Buffer.concat(chunks).toString();
+}
+function sanitizeETag(etag) {
+  return etag.replace(/^(?:"|"|")|(?:"|"|")$/g, "");
+}
+function uploadPartParser(body) {
+  if (/<(?:\w+:)?Error(?:\s|>)/.test(body))
+    throw new Error("MinIO multipart upload returned an XML error");
+  const etag = body.match(/<(?:\w+:)?ETag>([^<]*)<\/(?:\w+:)?ETag>/)?.[1];
+  if (!etag)
+    throw new Error("No ETag found in multipart upload response");
+  return { ETag: etag };
+}
+
+// src/utils/Uploader.ts
+var Logger = consoleLogger;
+var generateUploadId = () => Date.now().toString(16) + Array.from({ length: 16 }, () => Math.floor(Math.random() * 16).toString(16)).join("");
+var uploadSessions = new Map;
+
+class Uploader {
+  options;
+  name = "minio";
+  static agent;
+  static closing;
+  static pendingOperations = new Set;
+  static async runOperation(operation) {
+    if (Uploader.closing)
+      throw new Error("MinIO client is closing");
+    if (!Uploader.client)
+      throw new Error("MinIO client is not initialized. Call `Uploader.init()` first.");
+    let complete;
+    const pending = new Promise((resolve) => {
+      complete = resolve;
+    });
+    Uploader.pendingOperations.add(pending);
+    try {
+      return await operation();
+    } finally {
+      Uploader.pendingOperations.delete(pending);
+      complete();
+    }
+  }
+  static retainStream(stream) {
+    let complete;
+    const pending = new Promise((resolve) => {
+      complete = resolve;
+    });
+    Uploader.pendingOperations.add(pending);
+    const cleanup = finished(stream, () => {
+      cleanup();
+      Uploader.pendingOperations.delete(pending);
+      complete();
+    });
+  }
+  static client;
+  static clientEndpoint;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  async setup(context) {
+    if (Uploader.client)
+      throw new Error("MinIO client is already initialized");
+    Logger = context.logger;
+    await Uploader.init(this.options);
+    context.onClose(() => Uploader.close());
+  }
+  static close() {
+    if (Uploader.closing)
+      return Uploader.closing;
+    const client = Uploader.client;
+    const agent = Uploader.agent;
+    Uploader.closing = (async () => {
+      try {
+        while (Uploader.pendingOperations.size)
+          await Promise.all([...Uploader.pendingOperations]);
+        const sessions = [...uploadSessions.values()];
+        const results = await Promise.allSettled(sessions.map((session) => client.abortMultipartUpload(session.bucket, session.fileName, session.uploadId)));
+        const failures = results.filter((result) => result.status === "rejected");
+        if (failures.length)
+          throw new AggregateError(failures.map((result) => result.reason), "Failed to abort MinIO uploads");
+      } finally {
+        try {
+          agent?.destroy();
+        } finally {
+          Uploader.client = undefined;
+          Uploader.clientEndpoint = undefined;
+          Uploader.agent = undefined;
+          uploadSessions.clear();
+          Logger = consoleLogger;
+        }
+      }
+    })().finally(() => {
+      Uploader.closing = undefined;
+    });
+    return Uploader.closing;
+  }
+  static async init(options) {
+    if (Uploader.closing)
+      throw new Error("MinIO client is closing");
+    try {
+      if (!Uploader.client && Uploader.hasValidConfig(options)) {
+        Logger.info("Connecting to minIO server...");
+        Uploader.agent = options.minioUseSSL !== false ? new HttpsAgent({ keepAlive: true }) : new HttpAgent({ keepAlive: true });
+        Uploader.client = new minio.Client({
+          transportAgent: Uploader.agent,
+          endPoint: options.minioHost,
+          port: options.minioPort,
+          useSSL: options.minioUseSSL,
+          accessKey: options.minioAccessKey,
+          secretKey: options.minioSecretKey,
+          region: options.minioRegion
+        });
+        this.clientEndpoint = options.minioHost;
+        Logger.info("Connecting to minIO server... SUCCESS!");
+      }
+    } catch (error) {
+      Uploader.agent?.destroy();
+      Uploader.agent = undefined;
+      Uploader.client = undefined;
+      Logger.error(new Error("Connecting to minIO server... ERROR!"));
+      throw error;
+    }
+  }
+  static hasValidConfig(options) {
+    if (options.minioHost && options.minioHost && options.minioAccessKey && options.minioSecretKey) {
+      return true;
+    } else {
+      throw new Error("Cannot initialize MinIO Client. Check your .env file");
+    }
+  }
+  static async upload(bucket, dir, uploads) {
+    return Uploader.runOperation(async () => {
+      try {
+        let files = [];
+        const isArray = Array.isArray(uploads);
+        if (isArray) {
+          files = uploads;
+        } else {
+          files.push(uploads);
+        }
+        let response = [];
+        for (let index = 0;index < files.length; index++) {
+          const file = files[index];
+          let filename = file.name.replace(/ /g, "_");
+          let newName = new Date;
+          let path = `/${bucket}/${dir}/${newName.getTime()}`;
+          let etag = await Uploader.client.putObject(bucket, `${dir}/${newName.getTime()}`, file.data, file.size, { "Content-type": file.mimetype });
+          response.push({
+            etag,
+            path,
+            bucket,
+            directory: dir,
+            objectName: filename,
+            mimeType: file.mimetype,
+            location: `https://${process.env.MINIO_ENDPOINT || Uploader.clientEndpoint}${path}`,
+            filesize: file.size
+          });
+        }
+        return isArray ? response : response[0];
+      } catch (error) {
+        throw error;
+      }
+    });
+  }
+  async preview(bucket, file) {
+    return Uploader.runOperation(async () => {
+      try {
+        return await Uploader.client.presignedUrl("GET", bucket, file, 24 * 60 * 60);
+      } catch (error) {
+        throw error;
+      }
+    });
+  }
+  static async delete(bucketName, objectName, removeOpts) {
+    return Uploader.runOperation(async () => {
+      try {
+        const result = await Uploader.client.removeObject(bucketName, objectName, removeOpts);
+        return result;
+      } catch (error) {
+        throw error;
+      }
+    });
+  }
+  static async clearAllMultipartUploads(bucketName) {
+    return Uploader.runOperation(async () => {
+      return new Promise((resolve, reject) => {
+        const stream = Uploader.client.listIncompleteUploads(bucketName, "", true);
+        const pending = [];
+        const finish = async (streamError) => {
+          const results = await Promise.all(pending);
+          const errors = results.filter((result) => ("error" in result)).map((result) => result.error);
+          if (streamError)
+            errors.unshift(streamError);
+          if (errors.length)
+            reject(new AggregateError(errors, "Failed to clear MinIO multipart uploads"));
+          else
+            resolve();
+        };
+        stream.on("data", (upload) => {
+          pending.push(Promise.resolve().then(() => Uploader.client.abortMultipartUpload(bucketName, upload.key, upload.uploadId)).then(() => {
+            for (const [id, session] of uploadSessions) {
+              if (session.bucket === bucketName && session.fileName === upload.key && session.uploadId === upload.uploadId)
+                uploadSessions.delete(id);
+            }
+            return {};
+          }, (error) => ({ error })));
+        });
+        stream.on("end", () => {
+          finish();
+        });
+        stream.on("error", (error) => {
+          finish(error);
+        });
+      });
+    });
+  }
+  static async initiateUpload(bucket, fileName, metadata = {}) {
+    return Uploader.runOperation(async () => {
+      try {
+        const uploadId = generateUploadId();
+        const pathName = `stream/${uploadId}`;
+        const uploadInfo = await Uploader.client.initiateNewMultipartUpload(bucket, pathName, metadata);
+        uploadSessions.set(uploadId, {
+          bucket,
+          uploadId: uploadInfo,
+          minioUploadId: uploadInfo,
+          fileName: pathName,
+          objectName: fileName,
+          parts: [],
+          metadata,
+          createdAt: new Date
+        });
+        return {
+          uploadId,
+          minioUploadId: uploadInfo,
+          pathName,
+          message: "Upload session initialized"
+        };
+      } catch (error) {
+        throw error;
+      }
+    });
+  }
+  static async uploadChunk(uploadSessionId, chunkNumber, chunkData) {
+    return Uploader.runOperation(async () => {
+      try {
+        const session = uploadSessions.get(uploadSessionId);
+        if (!session)
+          throw new Error(`Upload session ${uploadSessionId} not found`);
+        let binaryData;
+        if (typeof chunkData === "string")
+          binaryData = Buffer.from(chunkData, "binary");
+        else if (chunkData instanceof Buffer)
+          binaryData = chunkData;
+        else
+          binaryData = Buffer.from(chunkData);
+        const partConfig = {
+          bucketName: session.bucket,
+          objectName: session.fileName,
+          uploadID: session.uploadId,
+          partNumber: chunkNumber,
+          headers: {
+            "Content-Type": "application/octet-stream",
+            "Content-Length": binaryData.length.toString()
+          }
+        };
+        const result = await this.uploadPart(partConfig, binaryData);
+        session.parts = session.parts.filter((part) => part.part !== chunkNumber);
+        session.parts.push({ part: chunkNumber, etag: result.etag });
+        return {
+          uploadId: uploadSessionId,
+          chunkNumber,
+          etag: result.etag,
+          key: result.key,
+          part: result.part,
+          uploadedPart: session.parts.length,
+          message: `Chunk ${chunkNumber} uploaded successfully`
+        };
+      } catch (error) {
+        Logger.error(error);
+        throw error;
+      }
+    });
+  }
+  static async completeUpload(uploadSessionId) {
+    return Uploader.runOperation(async () => {
+      try {
+        const session = uploadSessions.get(uploadSessionId);
+        if (!session)
+          throw new Error("Upload session not found");
+        const sortedParts = session.parts.sort((a, b) => a.part - b.part);
+        const result = await Uploader.client.completeMultipartUpload(session.bucket, session.fileName, session.uploadId, sortedParts);
+        const currateResult = {
+          etag: result,
+          path: session.fileName,
+          bucket: session.bucket,
+          location: `https://${this.clientEndpoint}/${session.bucket}/${session.fileName}`,
+          fileSize: !isNaN(Number(session.metadata?.["X-Amz-meta-filesize"])) ? Number(session.metadata["X-Amz-meta-filesize"]) : 0,
+          mimeType: session.metadata["Content-Type"] || "application/octet-stream",
+          objectName: session.objectName
+        };
+        uploadSessions.delete(uploadSessionId);
+        return currateResult;
+      } catch (error) {
+        console.error("Error completing upload:", error);
+        throw error;
+      }
+    });
+  }
+  static async streamDownload(res, { bucket, objectKey, objectName }) {
+    return Uploader.runOperation(async () => {
+      try {
+        const stat = await Uploader.client.statObject(bucket, objectKey);
+        res.setHeader("Content-Disposition", `attachment; filename="${objectName}"`);
+        res.setHeader("Content-Type", stat.metaData["content-type"] || "application/octet-stream");
+        res.setHeader("Content-Length", stat.size);
+        const stream = await Uploader.client.getObject(bucket, objectKey);
+        Uploader.retainStream(stream);
+        stream.on("error", (err) => {
+          Logger.error(err);
+          if (!res.headersSent) {
+            res.status(500).json({ error: "Download failed" });
+          }
+        });
+        try {
+          stream.pipe(res);
+        } catch (error) {
+          stream.destroy();
+          throw error;
+        }
+      } catch (error) {
+        throw error;
+      }
+    });
+  }
+  static uploadPart = async (partConfig, payload) => {
+    return Uploader.runOperation(async () => {
+      const { bucketName, objectName, uploadID, partNumber, headers } = partConfig;
+      const method = "PUT";
+      const query = `uploadId=${encodeURIComponent(uploadID)}&partNumber=${partNumber}`;
+      const requestOptions = { method, bucketName, objectName, query, headers };
+      const res = await Uploader.client.makeRequestAsync(requestOptions, payload);
+      const body = await readAsString(res);
+      let partRes;
+      if (body && body.trim())
+        partRes = uploadPartParser(body);
+      else if (res.headers && res.headers.etag)
+        partRes = { ETag: res.headers.etag };
+      else
+        throw new Error("No ETag found in response body or headers");
+      if (!partRes?.ETag)
+        throw new Error("No ETag found in response body or headers");
+      return {
+        etag: sanitizeETag(partRes.ETag),
+        key: objectName,
+        part: partNumber
+      };
+    });
+  };
+}
+export {
+  Uploader
+};

package/dist/plugin/index.d.ts

@@ -0,0 +1,16 @@
+import type { PluginDefinition } from '@beespoke/micro-server';
+export interface MinioPluginOptions {
+    host: string;
+    port?: number;
+    useSSL?: boolean;
+    accessKey: string;
+    secretKey: string;
+    region?: string;
+}
+declare module '@beespoke/micro-server' {
+    interface PluginOptionsRegistry {
+        '@beespoke/micro-server-minio': MinioPluginOptions;
+    }
+}
+declare const definition: PluginDefinition<MinioPluginOptions>;
+export default definition;

package/dist/plugin/index.js

@@ -0,0 +1,37 @@
+// src/plugin/index.ts
+import { Uploader } from "../index.js";
+var definition = {
+  name: "@beespoke/micro-server-minio",
+  validate(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options))
+      throw new Error("MinIO options must be an object");
+    const values = options;
+    const keys = ["host", "port", "useSSL", "accessKey", "secretKey", "region"];
+    if (Object.keys(values).some((key) => !keys.includes(key)))
+      throw new Error("MinIO options contain an unknown field");
+    for (const key of ["host", "accessKey", "secretKey"]) {
+      if (typeof values[key] !== "string" || !values[key].trim())
+        throw new Error(`MinIO ${key} must be a nonempty string`);
+    }
+    if (values.region !== undefined && (typeof values.region !== "string" || !values.region.trim()))
+      throw new Error("MinIO region must be a nonempty string");
+    if (values.port !== undefined && (!Number.isInteger(values.port) || values.port < 1 || values.port > 65535))
+      throw new Error("MinIO port must be an integer between 1 and 65535");
+    if (values.useSSL !== undefined && typeof values.useSSL !== "boolean")
+      throw new Error("MinIO useSSL must be a boolean");
+  },
+  create(options) {
+    return new Uploader({
+      minioHost: options.host,
+      minioPort: options.port,
+      minioUseSSL: options.useSSL,
+      minioAccessKey: options.accessKey,
+      minioSecretKey: options.secretKey,
+      minioRegion: options.region
+    });
+  }
+};
+var plugin_default = definition;
+export {
+  plugin_default as default
+};

package/dist/support.d.ts

@@ -0,0 +1,18 @@
+export interface Logger {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+export type LifecycleHook = () => void | Promise<void>;
+export interface PluginContext {
+    readonly logger: Logger;
+    readonly configDir: string;
+    onStart(hook: LifecycleHook): void;
+    onClose(hook: LifecycleHook): void;
+}
+export interface ServerPlugin {
+    readonly name: string;
+    setup(context: PluginContext): void | Promise<void>;
+}
+export declare const consoleLogger: Logger;

package/dist/types/MinioOptions.d.ts

@@ -0,0 +1,10 @@
+export interface MinioOptions {
+    minioHost?: string;
+    minioPort?: number;
+    minioAccessKey?: string;
+    minioSecretKey?: string;
+    minioUseSSL?: boolean;
+    minioRegion?: string;
+}
+/** The MinIO-owned subset of the legacy application options. */
+export type ApplicationOptionType = MinioOptions;

package/dist/types/UploadedFileType.d.ts

@@ -0,0 +1,74 @@
+export type UploadedFileType = {
+    etag?: string;
+    path?: string;
+    bucket?: string;
+    directory?: string;
+    objectName?: string;
+    mimeType?: string;
+    location?: string;
+    filesize?: number;
+};
+export type InitUpload = {
+    uploadId: string;
+    minioUploadId: string;
+    pathName: string;
+    message: string;
+};
+export type UploadPartConfig = {
+    bucketName: string;
+    objectName: string;
+    uploadID: string;
+    partNumber: number;
+    headers: unknown;
+};
+export type UploadSession = {
+    bucket: string;
+    uploadId: string;
+    fileName: string;
+    objectName: string;
+    minioUploadId: string;
+    parts: Array<{
+        part: number;
+        etag: string;
+    }>;
+    metadata?: Record<string, string>;
+    createdAt: Date;
+};
+export type UploadChunk = {
+    uploadId: string;
+    chunkNumber: number;
+    etag: string;
+    key: string;
+    part: number;
+    uploadedPart: number;
+    message: string;
+};
+export type CompleteUploadResult = {
+    etag: {
+        versionId: string;
+        etag: string;
+    };
+    path: string;
+    bucket: string;
+    location: string;
+    fileSize: number;
+    mimeType: string;
+    objectName: string;
+};
+export type UploadTypes = {
+    bucket: string;
+    objectKey: string;
+    objectName: string;
+};
+export type UploadPart = {
+    etag: string;
+    key: string;
+    part: number;
+};
+/** Minimal buffered file input; compatible with Express upload middleware. */
+export type UploadedFile = {
+    name: string;
+    data: Buffer;
+    size: number;
+    mimetype: string;
+};

package/dist/utils/Uploader.d.ts

@@ -0,0 +1,137 @@
+import type { PluginContext, ServerPlugin } from '../support.js';
+import type { MinioOptions as ApplicationOptionType } from '../types/MinioOptions.js';
+import * as minio from 'minio';
+import type { UploadedFile, UploadedFileType, InitUpload, UploadChunk, CompleteUploadResult, UploadTypes, UploadPart } from '../types/UploadedFileType.js';
+import type { RemoveOptions } from 'minio';
+export default class Uploader implements ServerPlugin {
+    private readonly options;
+    readonly name = "minio";
+    private static agent;
+    private static closing;
+    private static readonly pendingOperations;
+    /** Reserve before invoking the operation so close can drain every accepted call. */
+    private static runOperation;
+    /** A piped download remains active after streamDownload has returned. */
+    private static retainStream;
+    static client: minio.Client;
+    static clientEndpoint: string;
+    constructor(options?: ApplicationOptionType);
+    setup(context: PluginContext): Promise<void>;
+    /** Abort locally tracked uploads and release only this client's HTTP agent. */
+    static close(): Promise<void>;
+    /**
+     * Initializes the minIO client instance
+     */
+    static init(options: ApplicationOptionType): Promise<void>;
+    /**
+     * checks .env variables if properly configured
+     */
+    static hasValidConfig(options: ApplicationOptionType): boolean;
+    /**
+     *
+     * @param bucket {string} The bucket name in minIO
+     * @param dir {string} The directory where the files are stored
+     * @param uploads {Array<UploadedFile> | UploadedFile} file(s) to be uploaded
+     * @returns
+     */
+    static upload(bucket: string, dir: string, uploads: Array<UploadedFile> | UploadedFile): Promise<Array<UploadedFileType> | UploadedFileType>;
+    /**
+     *
+     * @param bucket {string} bucket name
+     * @param file {string} file directory
+     */
+    preview(bucket: string, file: string): Promise<string>;
+    static delete(bucketName: string, objectName: string, removeOpts?: RemoveOptions): Promise<void>;
+    /**
+     * Permanently cancels all pending multipart uploads within a specified S3/MinIO bucket.
+     * @description
+     *  This is a cleanup utility. Incomplete multipart uploads occupy storage space but are not visible as objects. This method iterates through the bucket's "incomplete" stream and issues an abort command for each. Use this to recover storage or clear stuck uploads after a service interruption.
+     * @param {string} bucketName - The unique identifier of the target MinIO bucket.
+     * @returns {Promise<void>} Resolves when the stream has finished processing all abort requests.
+     * @throws {Error} If the bucket is inaccessible or the list operation fails.
+     * @example
+     *  await Uploader.clearAllMultipartUploads('temp-uploads');
+     */
+    static clearAllMultipartUploads(bucketName: string): Promise<void>;
+    /**
+     * Starts a new multipart upload session and registers it in the local session cache.
+     * @description
+     * This method performs two actions:
+     *  1. Requests a new Multipart Upload ID from the MinIO/S3 server.
+     *  2. Initializes an internal tracking session in `uploadSessions` for part management.
+     * @param {string} bucket - Target bucket name.
+     * @param {string} fileName - The final destination filename/path.
+     * @param {Record<string, string>} [metadata={}] - Key-value pairs for S3 metadata.
+     * - Standard headers: `Content-Type`, `Cache-Control`, etc.
+     * - Custom tags: Use `X-Amz-meta-` prefix for custom attributes.
+     * @returns {Promise<InitUpload>}
+     *  Returns the internal session ID and the provider's upload ID.
+     * @throws {Error} If the connection to MinIO fails or the bucket does not exist.
+     */
+    static initiateUpload(bucket: string, fileName: string, metadata?: Record<string, string>): Promise<InitUpload>;
+    /**
+     * Processes and uploads a single data part to an active multipart session.
+     * @description
+     * This method normalizes various input formats (Buffer, string, or Uint8Array) into a binary Buffer, dispatches the upload to MinIO via `uploadPart`, and updates the  internal session state with the returned ETag.
+     * @param {string} uploadSessionId - The internal UUID generated during `initiateUpload`.
+     * @param {number} chunkNumber - The 1-based index of the part.
+     * @param {Buffer | string | Uint8Array} chunkData - The raw binary data or encoded string.
+     * @returns {Promise<UploadChunk>} Returns metadata about the uploaded part, including:
+     * - `etag`: The S3 identifier for this specific part (required for completion).
+     * - `uploadedPart`: The total count of parts successfully tracked in this session so far.
+     */
+    static uploadChunk(uploadSessionId: string, chunkNumber: number, chunkData: Buffer | string | Uint8Array): Promise<UploadChunk>;
+    /**
+     * Finalizes the multipart upload by assembling all uploaded parts into a single object.
+     * @description
+     * This method performs the final handshake with MinIO/S3. It:
+     * 1. Retrieves and sorts the accumulated ETags by part number (mandatory for S3 compliance).
+     * 2. Signals the storage server to merge the data parts.
+     * 3. Extracts file metadata (size, mime-type) from the session.
+     * 4. Purges the internal `uploadSessions` cache to prevent memory leaks.
+     * @param {string} uploadSessionId - The internal tracking ID of the session to be closed.
+     * @returns {Promise<Object>} A curated result object containing:
+     * - `etag`: The final entity tag for the completed object.
+     * - `location`: The public/internal URL of the uploaded file.
+     * - `fileSize`: Parsed size from the 'X-Amz-meta-filesize' metadata.
+     * @throws {Error} If parts are missing, the session is not found, or S3 assembly fails.
+     */
+    static completeUpload(uploadSessionId: string): Promise<CompleteUploadResult>;
+    /**
+     * Streams an object from storage directly to an HTTP response.
+     * @description
+     * Fetches object metadata (stat) to populate necessary download headers before
+     * piping the data stream to the client. This avoids loading the entire file
+     * into memory, making it efficient for large file transfers.
+     * * @param {Response} res - The Express/Node.js response object.
+     * @param {UploadTypes} options - Configuration object containing:
+     * - `bucket`: Target bucket name.
+     * - `objectKey`: The internal storage path (e.g., 'stream/123').
+     * - `objectName`: The "friendly" filename for the user's browser.
+     * @returns {Promise<void>} Resolves once the stream has been successfully piped.
+     * @throws {Error} If the object does not exist or metadata cannot be retrieved.
+     */
+    static streamDownload(res: any, { bucket, objectKey, objectName }: UploadTypes): Promise<void>;
+    /**
+     * Executes a low-level Multipart Upload Part request.
+     * * @description
+     *  This is a custom wrapper around the S3/MinIO PUT Object Part API. It manually constructs the query parameters and headers required for a part upload. Crucially, it handles inconsistent server responses by attempting to extract the ETag from both the response XML body and the HTTP headers.
+     * @param {Object} partConfig - Configuration for the specific part.
+     * @param {string} partConfig.bucketName - Target bucket.
+     * @param {string} partConfig.objectName - The internal path/key of the object.
+     * @param {string} partConfig.uploadID - The ID generated by `initiateNewMultipartUpload`.
+     * @param {number} partConfig.partNumber - 1-based index of the part.
+     * @param {unknown} partConfig.headers - HTTP headers (e.g., Content-Length, Content-MD5).
+     * @param {any} [payload] - The binary data buffer for this part.
+     * @returns {Promise<UploadPart>}
+     *  Returns a sanitized ETag required for the final `completeUpload` call.
+     * @throws {Error} If no ETag is found in the response or the network request fails.
+     */
+    static uploadPart: (partConfig: {
+        bucketName: string;
+        objectName: string;
+        uploadID: string;
+        partNumber: number;
+        headers: unknown;
+    }, payload?: any) => Promise<UploadPart>;
+}

package/dist/utils/multipart.d.ts

@@ -0,0 +1,6 @@
+import type { Readable } from 'node:stream';
+export declare function readAsString(response: Readable): Promise<string>;
+export declare function sanitizeETag(etag: string): string;
+export declare function uploadPartParser(body: string): {
+    ETag: string;
+};

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@beespoke/micro-server-minio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.5",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "import": "./dist/plugin/index.js",
+      "default": "./dist/plugin/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun ../../scripts/build-package.ts",
+    "test": "bun test tests"
+  },
+  "dependencies": {
+    "minio": "^8.0.0",
+    "@types/node": "^24.0.0"
+  },
+  "peerDependencies": {
+    "@beespoke/micro-server": "^2.0.5"
+  },
+  "peerDependenciesMeta": {
+    "@beespoke/micro-server": {
+      "optional": true
+    }
+  },
+  "license": "MIT"
+}