@beespoke/micro-server-s3 0.0.0-stage → 2.0.3

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @beespoke/micro-server-s3
 
-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.
+S3-compatible uploads, multipart sessions, object deletion, and XML/stream helpers.
+
+Supports Node 24+ and Bun 1.3.14+.
+
+## Install
+
+```sh
+npm install @beespoke/micro-server @beespoke/micro-server-s3
+```
+
+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-s3'],
+    pluginOptions: {
+        '@beespoke/micro-server-s3': {
+            endpoint: process.env.S3_ENDPOINT!,
+            region: process.env.S3_REGION!,
+            accessKeyId: process.env.S3_ACCESS_KEY_ID!,
+            secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
+        },
+    },
+});
+```
+
+Requires an S3-compatible endpoint and credentials. `endpoint` must be an HTTP or HTTPS URL. Optional `forcePathStyle` controls path-style addressing; `publicUrl` provides a public base URL. Include a bucket segment in `publicUrl` when required by your public URL layout. Buckets remain operation arguments.
+
+## Storage API
+
+The root exports `UploaderS3`, `S3Options`, `DeleteObjectRequest`, attachment types, and `mimeTypes`. `UploaderS3` provides upload/multipart operations and `deleteFile`. Utility exports include `getMimeType`, `readAsBuffer`, `readAsString`, `parseXml`, `uploadPartParser`, and `sanitizeETag`.
+
+Direct initialization uses `await UploaderS3.init({ s3Endpoint, s3region, s3AccessKeyId, s3SecretAccessKey })`; the spelling `s3region` is lowercase in the direct API. Close with `await UploaderS3.close()`. Shutdown drains tracked operations and aborts unfinished multipart uploads. Plugin configuration uses the shorter names shown above.
+
+## 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-s3/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,5 @@
+export { default as UploaderS3 } from './utils/UploaderS3.js';
+export type { S3Options, ApplicationOptionType } from './types/S3Options.js';
+export { mimeTypes } from './types/AttachmentMetadataTypes.js';
+export type { AttachmentMetadataType, DeleteObjectRequest } from './types/AttachmentMetadataTypes.js';
+export { getMimeType, readAsBuffer, readAsString, parseXml, uploadPartParser, sanitizeETag } from './utils/helpers.js';

package/dist/index.js

@@ -0,0 +1,404 @@
+// 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/UploaderS3.ts
+import { S3, ListBucketsCommand, CreateMultipartUploadCommand, UploadPartCommand, CompleteMultipartUploadCommand, AbortMultipartUploadCommand, ListMultipartUploadsCommand, PutObjectCommand, DeleteObjectCommand, HeadObjectCommand } from "@aws-sdk/client-s3";
+
+// src/types/AttachmentMetadataTypes.ts
+var mimeTypes = {
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  webp: "image/webp",
+  bmp: "image/bmp",
+  svg: "image/svg+xml",
+  mp4: "video/mp4",
+  mov: "video/quicktime",
+  avi: "video/x-msvideo",
+  mkv: "video/x-matroska",
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  pdf: "application/pdf",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  txt: "text/plain",
+  json: "application/json",
+  html: "text/html",
+  css: "text/css",
+  js: "application/javascript",
+  ts: "application/typescript"
+};
+
+// src/utils/helpers.ts
+import { XMLParser } from "fast-xml-parser";
+var getMimeType = (fileName) => {
+  const extension = fileName.split(".").pop()?.toLowerCase();
+  return extension ? mimeTypes[extension] || null : null;
+};
+async function readAsBuffer(res) {
+  return new Promise((resolve, reject) => {
+    const body = [];
+    res.on("data", (chunk) => body.push(chunk)).on("error", (e) => reject(e)).on("end", () => resolve(Buffer.concat(body)));
+  });
+}
+async function readAsString(res) {
+  const body = await readAsBuffer(res);
+  return body.toString();
+}
+var parseXml = (xml) => {
+  const fxp = new XMLParser({ numberParseOptions: { eNotation: false, hex: true, leadingZeros: true } });
+  const result = fxp.parse(xml);
+  if (result.Error) {
+    throw result.Error;
+  }
+  return result;
+};
+var uploadPartParser = (xml) => {
+  const xmlObj = parseXml(xml);
+  return xmlObj.CopyPartResult;
+};
+var sanitizeETag = (etag) => {
+  const replaceChars = {
+    '"': "",
+    """: "",
+    """: "",
+    """: "",
+    "&#x00022": ""
+  };
+  return etag.replace(/^("|"|")|("|"|")$/g, (m) => replaceChars[m]);
+};
+
+// src/utils/UploaderS3.ts
+var Logger = consoleLogger;
+
+class UploaderS3 {
+  options;
+  name = "s3";
+  static options = {};
+  static sessions = new Map;
+  static closing;
+  static pendingOperations = new Set;
+  static async runOperation(operation) {
+    if (UploaderS3.closing)
+      throw new Error("S3 client is closing");
+    if (!UploaderS3.client)
+      throw new Error("S3 client is not initialized. Call `UploaderS3.init()` first.");
+    let complete;
+    const pending = new Promise((resolve) => {
+      complete = resolve;
+    });
+    UploaderS3.pendingOperations.add(pending);
+    try {
+      return await operation();
+    } finally {
+      UploaderS3.pendingOperations.delete(pending);
+      complete();
+    }
+  }
+  constructor(options = {}) {
+    this.options = options;
+  }
+  async setup(context) {
+    if (UploaderS3.client)
+      throw new Error("S3 client is already initialized");
+    Logger = context.logger;
+    await UploaderS3.init(this.options);
+    context.onClose(() => UploaderS3.close());
+  }
+  static close() {
+    if (UploaderS3.closing)
+      return UploaderS3.closing;
+    const client = UploaderS3.client;
+    UploaderS3.closing = (async () => {
+      try {
+        while (UploaderS3.pendingOperations.size)
+          await Promise.all([...UploaderS3.pendingOperations]);
+        const sessions = [...UploaderS3.sessions.values()];
+        const results = await Promise.allSettled(sessions.map((session) => client.send(new AbortMultipartUploadCommand({
+          Bucket: session.bucket,
+          Key: session.key,
+          UploadId: session.uploadId
+        }))));
+        const failures = results.filter((result) => result.status === "rejected");
+        if (failures.length)
+          throw new AggregateError(failures.map((result) => result.reason), "Failed to abort S3 uploads");
+      } finally {
+        try {
+          client?.destroy();
+        } finally {
+          UploaderS3.client = undefined;
+          UploaderS3.options = {};
+          UploaderS3.uploadSessions = {};
+          UploaderS3.sessions.clear();
+          Logger = consoleLogger;
+        }
+      }
+    })().finally(() => {
+      UploaderS3.closing = undefined;
+    });
+    return UploaderS3.closing;
+  }
+  static client;
+  static uploadSessions = {};
+  static async init(options) {
+    if (UploaderS3.closing)
+      throw new Error("S3 client is closing");
+    if (!UploaderS3.hasValidConfig(options))
+      throw new Error("Cannot initialize S3 client: endpoint, region and credentials are required");
+    try {
+      if (!UploaderS3.client) {
+        Logger.info("Connecting to S3 server...");
+        UploaderS3.client = new S3({
+          forcePathStyle: options.s3ForcePathStyle,
+          endpoint: options.s3Endpoint,
+          region: options.s3region,
+          credentials: {
+            accessKeyId: options.s3AccessKeyId,
+            secretAccessKey: options.s3SecretAccessKey
+          }
+        });
+        UploaderS3.options = { ...options };
+        Logger.info("Connected to S3 server successfully!");
+      }
+    } catch (error) {
+      UploaderS3.client?.destroy();
+      UploaderS3.client = undefined;
+      UploaderS3.options = {};
+      Logger.error(error);
+      throw error;
+    }
+  }
+  static hasValidConfig(options) {
+    return Boolean(options.s3AccessKeyId && options.s3Endpoint && options.s3SecretAccessKey && options.s3region);
+  }
+  static async listBuckets() {
+    return UploaderS3.runOperation(async () => {
+      if (!UploaderS3.client) {
+        throw new Error("S3 client is not initialized. Call `UploaderS3.init()` first.");
+      }
+      try {
+        Logger.info("Fetching list of buckets...");
+        const data = await UploaderS3.client.send(new ListBucketsCommand({}));
+        Logger.info("Buckets:", data.Buckets);
+      } catch (error) {
+        Logger.error(error);
+        throw error;
+      }
+    });
+  }
+  static async startMultipartUpload(bucketName, key) {
+    return UploaderS3.runOperation(async () => {
+      if (!UploaderS3.client) {
+        throw new Error("S3 client is not initialized. Call `UploaderS3.init()` first.");
+      }
+      try {
+        const upload = await UploaderS3.client.send(new CreateMultipartUploadCommand({
+          Bucket: bucketName,
+          ACL: "public-read-write",
+          Key: key
+        }));
+        Logger.info("upload", upload);
+        if (!upload.UploadId)
+          throw new Error("S3 did not return a multipart upload ID");
+        UploaderS3.uploadSessions[key] = upload.UploadId;
+        UploaderS3.sessions.set(`${bucketName}\x00${key}\x00${upload.UploadId}`, { bucket: bucketName, key, uploadId: upload.UploadId });
+        return upload.UploadId;
+      } catch (error) {
+        Logger.error(error);
+        throw error;
+      }
+    });
+  }
+  static async uploadPart(bucketName, key, uploadId, partNumber, chunk) {
+    return UploaderS3.runOperation(async () => {
+      if (!UploaderS3.client) {
+        throw new Error("S3 client is not initialized. Call `UploaderS3.init()` first.");
+      }
+      try {
+        Logger.info("Uploading part", { bucketName, partNumber });
+        const response = await UploaderS3.client.send(new UploadPartCommand({
+          Bucket: bucketName,
+          Key: key,
+          UploadId: uploadId,
+          PartNumber: partNumber,
+          Body: chunk
+        }));
+        Logger.info("Part uploaded successfully:", response);
+        return response.ETag ?? null;
+      } catch (error) {
+        Logger.error(error);
+        throw error;
+      }
+    });
+  }
+  static async completeMultipartUpload(bucketName, key, uploadId, parts) {
+    return UploaderS3.runOperation(async () => {
+      if (!UploaderS3.client) {
+        throw new Error("S3 client is not initialized. Call `UploaderS3.init()` first.");
+      }
+      try {
+        Logger.info("Completing multipart upload for key:", key);
+        const response = await UploaderS3.client.send(new CompleteMultipartUploadCommand({
+          Bucket: bucketName,
+          Key: key,
+          UploadId: uploadId,
+          MultipartUpload: { Parts: parts }
+        }));
+        const metadata = {
+          Bucket: response.Bucket,
+          Etag: response.ETag,
+          Key: response.Key,
+          Location: response.Location ? /^https?:\/\//.test(response.Location) ? response.Location : `https://${response.Location}` : UploaderS3.objectUrl(bucketName, key),
+          MimeType: getMimeType(response.Key ?? "") ?? ""
+        };
+        UploaderS3.sessions.delete(`${bucketName}\x00${key}\x00${uploadId}`);
+        if (UploaderS3.uploadSessions[key] === uploadId)
+          delete UploaderS3.uploadSessions[key];
+        Logger.info("Multipart upload completed successfully.");
+        return metadata;
+      } catch (error) {
+        Logger.error(error);
+        throw error;
+      }
+    });
+  }
+  static async abortMultipartUpload(bucketName, key, uploadId) {
+    return UploaderS3.runOperation(async () => {
+      if (!UploaderS3.client) {
+        throw new Error("S3 client is not initialized. Call `UploaderS3.init()` first.");
+      }
+      try {
+        await UploaderS3.client.send(new AbortMultipartUploadCommand({
+          Bucket: bucketName,
+          Key: key,
+          UploadId: uploadId
+        }));
+        UploaderS3.sessions.delete(`${bucketName}\x00${key}\x00${uploadId}`);
+        if (UploaderS3.uploadSessions[key] === uploadId)
+          delete UploaderS3.uploadSessions[key];
+        Logger.info("Multipart upload aborted successfully.");
+      } catch (error) {
+        Logger.error(error);
+        throw error;
+      }
+    });
+  }
+  static async uploadFile(bucketName, key, fileContent, contentType) {
+    return UploaderS3.runOperation(async () => {
+      if (!UploaderS3.client) {
+        throw new Error("S3 client is not initialized. Call `UploaderS3.init()` first.");
+      }
+      try {
+        Logger.info("Uploading file directly to S3:", { bucketName, key });
+        const response = await UploaderS3.client.send(new PutObjectCommand({
+          Bucket: bucketName,
+          Key: key,
+          Body: fileContent,
+          ACL: "public-read-write",
+          ContentType: contentType
+        }));
+        Logger.info("File uploaded successfully:", { key, response });
+        const metadata = {
+          Bucket: bucketName,
+          Key: key,
+          Etag: response.ETag,
+          Location: UploaderS3.objectUrl(bucketName, key),
+          MimeType: contentType
+        };
+        return metadata;
+      } catch (error) {
+        Logger.error(error);
+        throw error;
+      }
+    });
+  }
+  static async deleteIncompleteUploads(bucketName) {
+    return UploaderS3.runOperation(async () => {
+      if (!UploaderS3.client) {
+        throw new Error("S3 client is not initialized. Call `UploaderS3.init()` first.");
+      }
+      try {
+        let isTruncated = true;
+        let marker;
+        let uploadIdMarker;
+        while (isTruncated) {
+          const listUploadsResponse = await UploaderS3.client.send(new ListMultipartUploadsCommand({
+            Bucket: bucketName,
+            KeyMarker: marker,
+            UploadIdMarker: uploadIdMarker
+          }));
+          for (const upload of listUploadsResponse.Uploads || []) {
+            const uploadId = upload.UploadId;
+            const key = upload.Key;
+            await UploaderS3.client.send(new AbortMultipartUploadCommand({
+              Bucket: bucketName,
+              Key: key,
+              UploadId: uploadId
+            }));
+            UploaderS3.sessions.delete(`${bucketName}\x00${key}\x00${uploadId}`);
+            if (key && UploaderS3.uploadSessions[key] === uploadId)
+              delete UploaderS3.uploadSessions[key];
+            Logger.info(`Aborted incomplete upload: ${key} with UploadId: ${uploadId}`);
+          }
+          marker = listUploadsResponse.NextKeyMarker;
+          uploadIdMarker = listUploadsResponse.NextUploadIdMarker;
+          isTruncated = listUploadsResponse.IsTruncated ?? false;
+        }
+        Logger.info("Completed deleting all incomplete uploads.");
+      } catch (error) {
+        Logger.error(error);
+        throw error;
+      }
+    });
+  }
+  static objectUrl(bucket, key) {
+    const options = UploaderS3.options;
+    if (options.s3PublicUrl)
+      return `${options.s3PublicUrl.replace(/\/$/, "")}/${key}`;
+    if (process.env.S3_REGION_CODE && process.env.S3_DOMAIN)
+      return `https://${bucket}.${process.env.S3_REGION_CODE}.cdn.${process.env.S3_DOMAIN}.com/${key}`;
+    const endpoint = new URL(options.s3Endpoint);
+    if (options.s3ForcePathStyle)
+      endpoint.pathname = `${endpoint.pathname.replace(/\/$/, "")}/${bucket}/${key}`;
+    else {
+      endpoint.hostname = `${bucket}.${endpoint.hostname}`;
+      endpoint.pathname = `${endpoint.pathname.replace(/\/$/, "")}/${key}`;
+    }
+    return endpoint.toString();
+  }
+  static async deleteFile(request) {
+    return UploaderS3.runOperation(async () => {
+      if (!UploaderS3.client)
+        throw new Error("S3 client is not initialized. Call `UploaderS3.init()` first.");
+      try {
+        const headCommand = new HeadObjectCommand({ Bucket: request.Bucket, Key: request.Key });
+        const { VersionId } = await UploaderS3.client.send(headCommand);
+        const payload = { ...request, VersionId: request.VersionId ?? VersionId };
+        const data = await UploaderS3.client.send(new DeleteObjectCommand(payload));
+        Logger.info(`deleted key : ${request.Key} `);
+        Logger.info(`data : ${JSON.stringify(data.$metadata)}`);
+      } catch (error) {
+        Logger.error(error);
+        throw error;
+      }
+    });
+  }
+}
+export {
+  uploadPartParser,
+  sanitizeETag,
+  readAsString,
+  readAsBuffer,
+  parseXml,
+  mimeTypes,
+  getMimeType,
+  UploaderS3
+};

package/dist/plugin/index.d.ts

@@ -0,0 +1,16 @@
+import type { PluginDefinition } from '@beespoke/micro-server';
+export interface S3PluginOptions {
+    endpoint: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    forcePathStyle?: boolean;
+    publicUrl?: string;
+}
+declare module '@beespoke/micro-server' {
+    interface PluginOptionsRegistry {
+        '@beespoke/micro-server-s3': S3PluginOptions;
+    }
+}
+declare const definition: PluginDefinition<S3PluginOptions>;
+export default definition;

package/dist/plugin/index.js

@@ -0,0 +1,46 @@
+// src/plugin/index.ts
+import { UploaderS3 } from "../index.js";
+var definition = {
+  name: "@beespoke/micro-server-s3",
+  validate(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options))
+      throw new Error("S3 options must be an object");
+    const values = options;
+    const keys = ["endpoint", "region", "accessKeyId", "secretAccessKey", "forcePathStyle", "publicUrl"];
+    if (Object.keys(values).some((key) => !keys.includes(key)))
+      throw new Error("S3 options contain an unknown field");
+    for (const key of ["endpoint", "region", "accessKeyId", "secretAccessKey"]) {
+      if (typeof values[key] !== "string" || !values[key].trim())
+        throw new Error(`S3 ${key} must be a nonempty string`);
+    }
+    for (const key of ["endpoint", "publicUrl"]) {
+      if (values[key] === undefined)
+        continue;
+      try {
+        if (typeof values[key] !== "string")
+          throw new Error;
+        const url = new URL(values[key]);
+        if (!["http:", "https:"].includes(url.protocol) || !url.hostname)
+          throw new Error;
+      } catch {
+        throw new Error(`S3 ${key} must be an HTTP or HTTPS URL`);
+      }
+    }
+    if (values.forcePathStyle !== undefined && typeof values.forcePathStyle !== "boolean")
+      throw new Error("S3 forcePathStyle must be a boolean");
+  },
+  create(options) {
+    return new UploaderS3({
+      s3Endpoint: options.endpoint,
+      s3region: options.region,
+      s3AccessKeyId: options.accessKeyId,
+      s3SecretAccessKey: options.secretAccessKey,
+      s3ForcePathStyle: options.forcePathStyle,
+      s3PublicUrl: options.publicUrl
+    });
+  }
+};
+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/AttachmentMetadataTypes.d.ts

@@ -0,0 +1,22 @@
+export type AttachmentMetadataType = {
+    Bucket?: string;
+    Etag?: string;
+    Key?: string;
+    Location?: string;
+    MimeType?: string;
+    Thumbnail?: string;
+    isHls?: boolean;
+};
+export type DeleteObjectRequest = {
+    Bucket: string;
+    Key: string;
+    MFA?: string;
+    VersionId?: string;
+    RequestPayer?: 'requester';
+    BypassGovernanceRetention?: boolean;
+    ExpectedBucketOwner?: string;
+    IfMatch?: string;
+    IfMatchLastModifiedTime?: Date;
+    IfMatchSize?: number;
+};
+export declare const mimeTypes: Record<string, string>;

package/dist/types/S3Options.d.ts

@@ -0,0 +1,11 @@
+export interface S3Options {
+    s3ForcePathStyle?: boolean;
+    s3Endpoint?: string;
+    s3region?: string;
+    s3AccessKeyId?: string;
+    s3SecretAccessKey?: string;
+    /** Optional public base URL; object keys are appended to it. */
+    s3PublicUrl?: string;
+}
+/** The S3-owned subset of the legacy application options. */
+export type ApplicationOptionType = S3Options;

package/dist/utils/UploaderS3.d.ts

@@ -0,0 +1,79 @@
+import type { S3Options as ApplicationOptionType } from "../types/S3Options.js";
+import type { PluginContext, ServerPlugin } from "../support.js";
+import { S3 } from "@aws-sdk/client-s3";
+import type { AttachmentMetadataType, DeleteObjectRequest } from "../types/AttachmentMetadataTypes.js";
+export default class UploaderS3 implements ServerPlugin {
+    private readonly options;
+    readonly name = "s3";
+    private static options;
+    private static sessions;
+    private static closing;
+    private static readonly pendingOperations;
+    /** Reserve before invoking the operation so close can drain every accepted call. */
+    private static runOperation;
+    constructor(options?: ApplicationOptionType);
+    setup(context: PluginContext): Promise<void>;
+    static close(): Promise<void>;
+    static client: S3;
+    static uploadSessions: Record<string, string>;
+    /**
+     * Initializes the S3 client instance
+     */
+    static init(options: ApplicationOptionType): Promise<void>;
+    /**
+     * Validates configuration options
+     */
+    static hasValidConfig(options: ApplicationOptionType): boolean;
+    /**
+     * Lists all available S3 buckets
+     */
+    static listBuckets(): Promise<void>;
+    /**
+     * Starts a new multipart upload session
+     * @param bucketName S3 bucket name
+     * @param key Key for the object in S3
+     */
+    static startMultipartUpload(bucketName: string, key: string): Promise<string>;
+    /**
+     * Uploads a file part to S3
+     * @param bucketName S3 bucket name
+     * @param key Key for the object in S3
+     * @param uploadId Multipart upload session ID
+     * @param partNumber Part number for the upload
+     * @param chunk Chunk of the file to upload
+     */
+    static uploadPart(bucketName: string, key: string, uploadId: string, partNumber: number, chunk: Buffer): Promise<string | null>;
+    /**
+     * Completes a multipart upload
+     * @param bucketName S3 bucket name
+     * @param key Key for the object in S3
+     * @param uploadId Multipart upload session ID
+     * @param parts List of uploaded parts
+     */
+    static completeMultipartUpload(bucketName: string, key: string, uploadId: string, parts: {
+        PartNumber: number;
+        ETag: string;
+    }[]): Promise<AttachmentMetadataType>;
+    /**
+     * Aborts a multipart upload
+     * @param bucketName S3 bucket name
+     * @param key Key for the object in S3
+     * @param uploadId Multipart upload session ID
+     */
+    static abortMultipartUpload(bucketName: string, key: string, uploadId: string): Promise<void>;
+    /**
+     * Directly uploads a file to S3 without chunking
+     * @param bucketName S3 bucket name
+     * @param key Key for the object in S3
+     * @param fileContent The content of the file to upload
+     * @param contentType The MIME type of the file
+     */
+    static uploadFile(bucketName: string, key: string, fileContent: Buffer | Uint8Array | Blob | string, contentType: string): Promise<AttachmentMetadataType>;
+    /**
+     * Deletes all incomplete multipart uploads in the specified bucket
+     * @param bucketName S3 bucket name
+     */
+    static deleteIncompleteUploads(bucketName: string): Promise<void>;
+    private static objectUrl;
+    static deleteFile(request: DeleteObjectRequest): Promise<void>;
+}

package/dist/utils/helpers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Retrieves the MIME type for a given file name based on its extension.
+ * @param fileName - The name of the file to extract the MIME type for.
+ * @returns The MIME type if found, or null if not found.
+ */
+export declare const getMimeType: (fileName: string) => string | null;
+/**
+ * Consumes a readable stream and aggregates all data chunks into a single Buffer.
+ * * @param {stream.Readable} res - The incoming data stream.
+ * @returns {Promise<Buffer>} A promise that resolves to the complete binary data.
+ */
+export declare function readAsBuffer(res: any): Promise<Buffer>;
+/**
+ * Reads an HTTP response body in its entirety and converts it to a string.
+ * Useful for parsing XML error messages or small metadata responses.
+ * * @param {http.IncomingMessage} res - The HTTP response object.
+ * @returns {Promise<string>} The body content decoded as a string.
+ */
+export declare function readAsString(res: any): Promise<string>;
+/**
+ * Parses an XML string into a JavaScript object using fast-xml-parser.
+ * * @throws {S3XmlError} If the XML contains an <Error> tag, it throws the error body.
+ */
+export declare const parseXml: (xml: string) => any;
+/**
+ * Specifically extracts the CopyPartResult from an S3 XML response.
+ * Used during multipart copy operations or part uploads that return XML.
+ */
+export declare const uploadPartParser: (xml: string) => any;
+/**
+ * Removes various encodings of double quotes from the start and end of an ETag.
+ * * @description
+ *  S3-compatible storage often returns ETags wrapped in literal quotes or
+ *  HTML entities. This regex-based sanitizer ensures only the raw hash remains.
+ * @param {string} [etag=''] - The raw ETag string from headers or XML.
+ * @returns {string} The cleaned ETag.
+ */
+export declare const sanitizeETag: (etag: string) => string;

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@beespoke/micro-server-s3",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.3",
+  "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": {
+    "@aws-sdk/client-s3": "^3.699.0",
+    "fast-xml-parser": "^5.3.4",
+    "@types/node": "^24.0.0"
+  },
+  "peerDependencies": {
+    "@beespoke/micro-server": "^2.0.3"
+  },
+  "peerDependenciesMeta": {
+    "@beespoke/micro-server": {
+      "optional": true
+    }
+  },
+  "license": "MIT"
+}