@headless-lms/adapter-storage-minio 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mdwt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# @headless-lms/adapter-storage-minio
+
+MinIO (S3-compatible) implementation of the `ObjectStorage` port from
+`@headless-lms/core/types`. Works against MinIO or any S3-compatible store; buckets
+are private, access is via short-lived presigned URLs only.
+
+The adapter reads no environment itself — the installation's `config.ts` parses
+env into a `MinioStorageConfig` and injects the constructed adapter:
+
+```ts
+import { MinioStorageAdapter } from "@headless-lms/adapter-storage-minio";
+
+const container = await createContainer(config, {
+  adapters: { storage: new MinioStorageAdapter(storageConfig) },
+});
+```
+
+## Environment variables (reference installation)
+
+| Variable                  | Required | Maps to                 | Notes                          |
+| ------------------------- | -------- | ----------------------- | ------------------------------ |
+| `STORAGE_ENDPOINT`        | yes      | `endPoint`              | Host only, no scheme.          |
+| `STORAGE_PORT`            | yes      | `port`                  |                                |
+| `STORAGE_USE_SSL`         | yes      | `useSSL`                | `"true"` / `"false"`.          |
+| `STORAGE_ACCESS_KEY`      | yes      | `accessKey`             |                                |
+| `STORAGE_SECRET_KEY`      | yes      | `secretKey`             |                                |
+| `STORAGE_REGION`          | yes      | `region`                |                                |
+| `STORAGE_BUCKET`          | yes      | `bucket`                | Created private if missing.    |
+| `STORAGE_UPLOAD_EXPIRY`   | no       | `uploadExpirySeconds`   | Default 300.                   |
+| `STORAGE_DOWNLOAD_EXPIRY` | no       | `downloadExpirySeconds` | Default 300.                   |

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { Logger, ObjectStorage, PresignDownloadInput, PresignedUpload, StoredObjectInfo } from "@headless-lms/core/types";
+//#region src/index.d.ts
+interface MinioStorageConfig {
+  endPoint: string;
+  port: number;
+  useSSL: boolean;
+  accessKey: string;
+  secretKey: string;
+  region: string;
+  bucket: string;
+  uploadExpirySeconds: number;
+  downloadExpirySeconds: number;
+}
+declare class MinioStorageAdapter implements ObjectStorage {
+  private readonly logger?;
+  private readonly client;
+  private readonly bucket;
+  private readonly region;
+  private readonly uploadExpiry;
+  private readonly downloadExpiry;
+  private ensured;
+  constructor(config: MinioStorageConfig, logger?: Logger | undefined);
+  /** Create the (private) bucket if it does not exist. Call once at startup. */
+  ensureBucket(): Promise<void>;
+  presignUpload(input: {
+    key: string;
+    contentType?: string;
+    expiresInSeconds?: number;
+  }): Promise<PresignedUpload>;
+  presignDownload(input: PresignDownloadInput): Promise<string>;
+  stat(key: string): Promise<StoredObjectInfo | null>;
+  remove(key: string): Promise<void>;
+}
+//#endregion
+export { MinioStorageAdapter, MinioStorageConfig };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,71 @@
+import { Client } from "minio";
+//#region src/index.ts
+var MinioStorageAdapter = class {
+	logger;
+	client;
+	bucket;
+	region;
+	uploadExpiry;
+	downloadExpiry;
+	ensured = false;
+	constructor(config, logger) {
+		this.logger = logger;
+		this.client = new Client({
+			endPoint: config.endPoint,
+			port: config.port,
+			useSSL: config.useSSL,
+			accessKey: config.accessKey,
+			secretKey: config.secretKey,
+			region: config.region
+		});
+		this.bucket = config.bucket;
+		this.region = config.region;
+		this.uploadExpiry = config.uploadExpirySeconds;
+		this.downloadExpiry = config.downloadExpirySeconds;
+	}
+	/** Create the (private) bucket if it does not exist. Call once at startup. */
+	async ensureBucket() {
+		if (this.ensured) return;
+		if (!await this.client.bucketExists(this.bucket).catch(() => false)) await this.client.makeBucket(this.bucket, this.region);
+		this.ensured = true;
+	}
+	async presignUpload(input) {
+		await this.ensureBucket();
+		const expiresInSeconds = input.expiresInSeconds ?? this.uploadExpiry;
+		return {
+			url: await this.client.presignedPutObject(this.bucket, input.key, expiresInSeconds),
+			method: "PUT",
+			key: input.key,
+			expiresInSeconds,
+			headers: input.contentType ? { "Content-Type": input.contentType } : {}
+		};
+	}
+	async presignDownload(input) {
+		await this.ensureBucket();
+		const expiresInSeconds = input.expiresInSeconds ?? this.downloadExpiry;
+		const respHeaders = {};
+		if (input.downloadFilename) respHeaders["response-content-disposition"] = `attachment; filename="${input.downloadFilename.replace(/"/g, "")}"`;
+		return this.client.presignedGetObject(this.bucket, input.key, expiresInSeconds, respHeaders);
+	}
+	async stat(key) {
+		try {
+			const s = await this.client.statObject(this.bucket, key);
+			const contentType = s.metaData?.["content-type"];
+			return {
+				key,
+				size: s.size,
+				...contentType ? { contentType } : {},
+				...s.lastModified ? { lastModified: s.lastModified.toISOString() } : {}
+			};
+		} catch {
+			return null;
+		}
+	}
+	async remove(key) {
+		await this.client.removeObject(this.bucket, key);
+	}
+};
+//#endregion
+export { MinioStorageAdapter };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// MinIO (S3-compatible) implementation of the ObjectStorage port. Private\n// buckets; access via short-lived presigned URLs only.\nimport { Client } from \"minio\";\nimport type {\n  Logger,\n  ObjectStorage,\n  PresignDownloadInput,\n  PresignedUpload,\n  StoredObjectInfo,\n} from \"@headless-lms/core/types\";\n\nexport interface MinioStorageConfig {\n  endPoint: string;\n  port: number;\n  useSSL: boolean;\n  accessKey: string;\n  secretKey: string;\n  region: string;\n  bucket: string;\n  uploadExpirySeconds: number;\n  downloadExpirySeconds: number;\n}\n\nexport class MinioStorageAdapter implements ObjectStorage {\n  private readonly client: Client;\n  private readonly bucket: string;\n  private readonly region: string;\n  private readonly uploadExpiry: number;\n  private readonly downloadExpiry: number;\n  private ensured = false;\n\n  constructor(\n    config: MinioStorageConfig,\n    private readonly logger?: Logger,\n  ) {\n    this.client = new Client({\n      endPoint: config.endPoint,\n      port: config.port,\n      useSSL: config.useSSL,\n      accessKey: config.accessKey,\n      secretKey: config.secretKey,\n      region: config.region,\n    });\n    this.bucket = config.bucket;\n    this.region = config.region;\n    this.uploadExpiry = config.uploadExpirySeconds;\n    this.downloadExpiry = config.downloadExpirySeconds;\n  }\n\n  /** Create the (private) bucket if it does not exist. Call once at startup. */\n  async ensureBucket(): Promise<void> {\n    if (this.ensured) {\n      return;\n    }\n    const exists = await this.client.bucketExists(this.bucket).catch(() => false);\n    if (!exists) {\n      await this.client.makeBucket(this.bucket, this.region);\n    }\n    this.ensured = true;\n  }\n\n  async presignUpload(input: {\n    key: string;\n    contentType?: string;\n    expiresInSeconds?: number;\n  }): Promise<PresignedUpload> {\n    await this.ensureBucket();\n    const expiresInSeconds = input.expiresInSeconds ?? this.uploadExpiry;\n    const url = await this.client.presignedPutObject(this.bucket, input.key, expiresInSeconds);\n    return {\n      url,\n      method: \"PUT\",\n      key: input.key,\n      expiresInSeconds,\n      headers: input.contentType ? { \"Content-Type\": input.contentType } : {},\n    };\n  }\n\n  async presignDownload(input: PresignDownloadInput): Promise<string> {\n    await this.ensureBucket();\n    const expiresInSeconds = input.expiresInSeconds ?? this.downloadExpiry;\n    const respHeaders: Record<string, string> = {};\n    if (input.downloadFilename) {\n      respHeaders[\"response-content-disposition\"] =\n        `attachment; filename=\"${input.downloadFilename.replace(/\"/g, \"\")}\"`;\n    }\n    return this.client.presignedGetObject(this.bucket, input.key, expiresInSeconds, respHeaders);\n  }\n\n  async stat(key: string): Promise<StoredObjectInfo | null> {\n    try {\n      const s = await this.client.statObject(this.bucket, key);\n      const contentType = s.metaData?.[\"content-type\"];\n      return {\n        key,\n        size: s.size,\n        ...(contentType ? { contentType } : {}),\n        ...(s.lastModified ? { lastModified: s.lastModified.toISOString() } : {}),\n      };\n    } catch {\n      return null;\n    }\n  }\n\n  async remove(key: string): Promise<void> {\n    await this.client.removeObject(this.bucket, key);\n  }\n}\n"],"mappings":";;AAuBA,IAAa,sBAAb,MAA0D;CAUrC;CATnB;CACA;CACA;CACA;CACA;CACA,UAAkB;CAElB,YACE,QACA,QACA;EADiB,KAAA,SAAA;EAEjB,KAAK,SAAS,IAAI,OAAO;GACvB,UAAU,OAAO;GACjB,MAAM,OAAO;GACb,QAAQ,OAAO;GACf,WAAW,OAAO;GAClB,WAAW,OAAO;GAClB,QAAQ,OAAO;EACjB,CAAC;EACD,KAAK,SAAS,OAAO;EACrB,KAAK,SAAS,OAAO;EACrB,KAAK,eAAe,OAAO;EAC3B,KAAK,iBAAiB,OAAO;CAC/B;;CAGA,MAAM,eAA8B;EAClC,IAAI,KAAK,SACP;EAGF,IAAI,CAAC,MADgB,KAAK,OAAO,aAAa,KAAK,MAAM,CAAC,CAAC,YAAY,KAAK,GAE1E,MAAM,KAAK,OAAO,WAAW,KAAK,QAAQ,KAAK,MAAM;EAEvD,KAAK,UAAU;CACjB;CAEA,MAAM,cAAc,OAIS;EAC3B,MAAM,KAAK,aAAa;EACxB,MAAM,mBAAmB,MAAM,oBAAoB,KAAK;EAExD,OAAO;GACL,KAAA,MAFgB,KAAK,OAAO,mBAAmB,KAAK,QAAQ,MAAM,KAAK,gBAAgB;GAGvF,QAAQ;GACR,KAAK,MAAM;GACX;GACA,SAAS,MAAM,cAAc,EAAE,gBAAgB,MAAM,YAAY,IAAI,CAAC;EACxE;CACF;CAEA,MAAM,gBAAgB,OAA8C;EAClE,MAAM,KAAK,aAAa;EACxB,MAAM,mBAAmB,MAAM,oBAAoB,KAAK;EACxD,MAAM,cAAsC,CAAC;EAC7C,IAAI,MAAM,kBACR,YAAY,kCACV,yBAAyB,MAAM,iBAAiB,QAAQ,MAAM,EAAE,EAAE;EAEtE,OAAO,KAAK,OAAO,mBAAmB,KAAK,QAAQ,MAAM,KAAK,kBAAkB,WAAW;CAC7F;CAEA,MAAM,KAAK,KAA+C;EACxD,IAAI;GACF,MAAM,IAAI,MAAM,KAAK,OAAO,WAAW,KAAK,QAAQ,GAAG;GACvD,MAAM,cAAc,EAAE,WAAW;GACjC,OAAO;IACL;IACA,MAAM,EAAE;IACR,GAAI,cAAc,EAAE,YAAY,IAAI,CAAC;IACrC,GAAI,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,YAAY,EAAE,IAAI,CAAC;GACzE;EACF,QAAQ;GACN,OAAO;EACT;CACF;CAEA,MAAM,OAAO,KAA4B;EACvC,MAAM,KAAK,OAAO,aAAa,KAAK,QAAQ,GAAG;CACjD;AACF"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@headless-lms/adapter-storage-minio",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "minio": "^8.0.7",
+    "@headless-lms/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.22.9",
+    "typescript": "^5.7.2"
+  },
+  "description": "MinIO/S3 storage adapter for the headless LMS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdwt/headless-lms.git",
+    "directory": "adapters/storage-minio"
+  },
+  "homepage": "https://github.com/mdwt/headless-lms#readme",
+  "bugs": {
+    "url": "https://github.com/mdwt/headless-lms/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}