tawa-storage 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# tawa-storage
+
+S3-compatible object storage SDK for the Tawa platform

package/dist/index.d.mts

@@ -0,0 +1,160 @@
+import { Readable } from 'node:stream';
+
+/** Configuration for creating a StorageClient */
+interface StorageClientConfig {
+    /** MinIO/S3 host (e.g., "64.23.181.20") */
+    readonly host: string;
+    /** MinIO/S3 port (default: 9000) */
+    readonly port?: number;
+    /** S3 access key ID */
+    readonly accessKey: string;
+    /** S3 secret access key */
+    readonly secretKey: string;
+    /** S3 region (default: "us-east-1") */
+    readonly region?: string;
+    /** Target bucket name */
+    readonly bucket: string;
+    /** Use SSL for connection (default: false) */
+    readonly useSSL?: boolean;
+}
+/** Options for upload operations */
+interface UploadOptions {
+    /** Content-Type header. Auto-detected from filename if omitted. */
+    readonly contentType?: string;
+    /** Custom metadata key-value pairs */
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+/** Options for presigned URL generation */
+interface SignedUrlOptions {
+    /** Expiry time in seconds (default: 3600 = 1 hour) */
+    readonly expiresIn?: number;
+}
+/** Result of a stat() call */
+interface ObjectStat {
+    /** Size in bytes */
+    readonly size: number;
+    /** ETag hash */
+    readonly etag: string;
+    /** Last modification timestamp */
+    readonly lastModified: Date;
+    /** Content-Type */
+    readonly contentType: string;
+}
+/** Item returned from list() */
+interface ListItem {
+    /** Object key (path) */
+    readonly key: string;
+    /** Size in bytes */
+    readonly size: number;
+    /** ETag hash */
+    readonly etag: string;
+    /** Last modification timestamp */
+    readonly lastModified: Date;
+}
+/** Error codes for StorageError */
+type StorageErrorCode = 'NOT_FOUND' | 'ACCESS_DENIED' | 'BUCKET_NOT_FOUND' | 'INVALID_CONFIG' | 'NETWORK_ERROR' | 'UPLOAD_FAILED' | 'DELETE_FAILED' | 'PRESIGN_FAILED' | 'UNKNOWN';
+/** Accepted data types for upload */
+type UploadData = Buffer | string | Readable;
+
+declare class StorageClient {
+    private readonly client;
+    private readonly bucket;
+    constructor(config: StorageClientConfig);
+    /**
+     * Create a StorageClient from environment variables.
+     *
+     * Reads: S3_HOST, S3_PORT, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY,
+     *        S3_REGION, S3_BUCKET
+     */
+    static fromEnv(): StorageClient;
+    /**
+     * Create a StorageClient for a named bucket.
+     *
+     * Reads S3_{NAME}_BUCKET for the bucket name, shares
+     * connection config (S3_HOST, etc.) from the environment.
+     */
+    static fromEnvNamed(name: string): StorageClient;
+    /**
+     * Upload data to the bucket.
+     * Accepts Buffer, string, or Readable stream.
+     * Content-type is auto-detected from the key if not provided.
+     */
+    upload(key: string, data: UploadData, options?: UploadOptions): Promise<void>;
+    /**
+     * Download an object and return its contents as a Buffer.
+     * For large files, use downloadStream() instead.
+     */
+    download(key: string): Promise<Buffer>;
+    /**
+     * Download an object as a Readable stream.
+     * Use this for large files to avoid loading everything into memory.
+     */
+    downloadStream(key: string): Promise<Readable>;
+    /**
+     * Delete one or more objects.
+     * Accepts a single key or an array of keys for bulk delete.
+     */
+    delete(keys: string | readonly string[]): Promise<void>;
+    /**
+     * List objects with an optional prefix.
+     * Returns a complete array (not a stream) for simplicity.
+     */
+    list(prefix?: string): Promise<readonly ListItem[]>;
+    /**
+     * Check if an object exists.
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get object metadata (size, etag, lastModified, contentType).
+     */
+    stat(key: string): Promise<ObjectStat>;
+    /**
+     * Generate a presigned download URL.
+     */
+    getSignedUrl(key: string, options?: SignedUrlOptions): Promise<string>;
+    /**
+     * Generate a presigned upload URL (PUT).
+     */
+    getUploadUrl(key: string, options?: SignedUrlOptions): Promise<string>;
+    private streamToBuffer;
+    private isNotFoundError;
+    private wrapError;
+}
+
+declare class StorageError extends Error {
+    readonly code: StorageErrorCode;
+    readonly statusCode: number;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: StorageErrorCode, statusCode?: number, cause?: unknown | undefined);
+}
+
+/**
+ * Detect content type from a file path or key name.
+ * Returns 'application/octet-stream' for unknown extensions.
+ */
+declare function detectContentType(key: string): string;
+
+/**
+ * Create a StorageClient.
+ *
+ * @example Single bucket (reads S3_BUCKET)
+ * ```typescript
+ * const storage = createStorage()
+ * await storage.upload('file.txt', Buffer.from('hello'))
+ * ```
+ *
+ * @example Named bucket (reads S3_UPLOADS_BUCKET)
+ * ```typescript
+ * const uploads = createStorage('uploads')
+ * ```
+ *
+ * @example Explicit config (for testing)
+ * ```typescript
+ * const storage = createStorage({ bucket: 'test', host: '127.0.0.1', accessKey: '...', secretKey: '...' })
+ * ```
+ */
+declare function createStorage(input?: string | (Partial<StorageClientConfig> & {
+    readonly bucket: string;
+})): StorageClient;
+
+export { type ListItem, type ObjectStat, type SignedUrlOptions, StorageClient, type StorageClientConfig, StorageError, type StorageErrorCode, type UploadData, type UploadOptions, createStorage, detectContentType };

package/dist/index.d.ts

@@ -0,0 +1,160 @@
+import { Readable } from 'node:stream';
+
+/** Configuration for creating a StorageClient */
+interface StorageClientConfig {
+    /** MinIO/S3 host (e.g., "64.23.181.20") */
+    readonly host: string;
+    /** MinIO/S3 port (default: 9000) */
+    readonly port?: number;
+    /** S3 access key ID */
+    readonly accessKey: string;
+    /** S3 secret access key */
+    readonly secretKey: string;
+    /** S3 region (default: "us-east-1") */
+    readonly region?: string;
+    /** Target bucket name */
+    readonly bucket: string;
+    /** Use SSL for connection (default: false) */
+    readonly useSSL?: boolean;
+}
+/** Options for upload operations */
+interface UploadOptions {
+    /** Content-Type header. Auto-detected from filename if omitted. */
+    readonly contentType?: string;
+    /** Custom metadata key-value pairs */
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+/** Options for presigned URL generation */
+interface SignedUrlOptions {
+    /** Expiry time in seconds (default: 3600 = 1 hour) */
+    readonly expiresIn?: number;
+}
+/** Result of a stat() call */
+interface ObjectStat {
+    /** Size in bytes */
+    readonly size: number;
+    /** ETag hash */
+    readonly etag: string;
+    /** Last modification timestamp */
+    readonly lastModified: Date;
+    /** Content-Type */
+    readonly contentType: string;
+}
+/** Item returned from list() */
+interface ListItem {
+    /** Object key (path) */
+    readonly key: string;
+    /** Size in bytes */
+    readonly size: number;
+    /** ETag hash */
+    readonly etag: string;
+    /** Last modification timestamp */
+    readonly lastModified: Date;
+}
+/** Error codes for StorageError */
+type StorageErrorCode = 'NOT_FOUND' | 'ACCESS_DENIED' | 'BUCKET_NOT_FOUND' | 'INVALID_CONFIG' | 'NETWORK_ERROR' | 'UPLOAD_FAILED' | 'DELETE_FAILED' | 'PRESIGN_FAILED' | 'UNKNOWN';
+/** Accepted data types for upload */
+type UploadData = Buffer | string | Readable;
+
+declare class StorageClient {
+    private readonly client;
+    private readonly bucket;
+    constructor(config: StorageClientConfig);
+    /**
+     * Create a StorageClient from environment variables.
+     *
+     * Reads: S3_HOST, S3_PORT, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY,
+     *        S3_REGION, S3_BUCKET
+     */
+    static fromEnv(): StorageClient;
+    /**
+     * Create a StorageClient for a named bucket.
+     *
+     * Reads S3_{NAME}_BUCKET for the bucket name, shares
+     * connection config (S3_HOST, etc.) from the environment.
+     */
+    static fromEnvNamed(name: string): StorageClient;
+    /**
+     * Upload data to the bucket.
+     * Accepts Buffer, string, or Readable stream.
+     * Content-type is auto-detected from the key if not provided.
+     */
+    upload(key: string, data: UploadData, options?: UploadOptions): Promise<void>;
+    /**
+     * Download an object and return its contents as a Buffer.
+     * For large files, use downloadStream() instead.
+     */
+    download(key: string): Promise<Buffer>;
+    /**
+     * Download an object as a Readable stream.
+     * Use this for large files to avoid loading everything into memory.
+     */
+    downloadStream(key: string): Promise<Readable>;
+    /**
+     * Delete one or more objects.
+     * Accepts a single key or an array of keys for bulk delete.
+     */
+    delete(keys: string | readonly string[]): Promise<void>;
+    /**
+     * List objects with an optional prefix.
+     * Returns a complete array (not a stream) for simplicity.
+     */
+    list(prefix?: string): Promise<readonly ListItem[]>;
+    /**
+     * Check if an object exists.
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get object metadata (size, etag, lastModified, contentType).
+     */
+    stat(key: string): Promise<ObjectStat>;
+    /**
+     * Generate a presigned download URL.
+     */
+    getSignedUrl(key: string, options?: SignedUrlOptions): Promise<string>;
+    /**
+     * Generate a presigned upload URL (PUT).
+     */
+    getUploadUrl(key: string, options?: SignedUrlOptions): Promise<string>;
+    private streamToBuffer;
+    private isNotFoundError;
+    private wrapError;
+}
+
+declare class StorageError extends Error {
+    readonly code: StorageErrorCode;
+    readonly statusCode: number;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: StorageErrorCode, statusCode?: number, cause?: unknown | undefined);
+}
+
+/**
+ * Detect content type from a file path or key name.
+ * Returns 'application/octet-stream' for unknown extensions.
+ */
+declare function detectContentType(key: string): string;
+
+/**
+ * Create a StorageClient.
+ *
+ * @example Single bucket (reads S3_BUCKET)
+ * ```typescript
+ * const storage = createStorage()
+ * await storage.upload('file.txt', Buffer.from('hello'))
+ * ```
+ *
+ * @example Named bucket (reads S3_UPLOADS_BUCKET)
+ * ```typescript
+ * const uploads = createStorage('uploads')
+ * ```
+ *
+ * @example Explicit config (for testing)
+ * ```typescript
+ * const storage = createStorage({ bucket: 'test', host: '127.0.0.1', accessKey: '...', secretKey: '...' })
+ * ```
+ */
+declare function createStorage(input?: string | (Partial<StorageClientConfig> & {
+    readonly bucket: string;
+})): StorageClient;
+
+export { type ListItem, type ObjectStat, type SignedUrlOptions, StorageClient, type StorageClientConfig, StorageError, type StorageErrorCode, type UploadData, type UploadOptions, createStorage, detectContentType };

package/dist/index.js

@@ -0,0 +1,394 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  StorageClient: () => StorageClient,
+  StorageError: () => StorageError,
+  createStorage: () => createStorage,
+  detectContentType: () => detectContentType
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_minio = require("minio");
+
+// src/errors.ts
+var StorageError = class extends Error {
+  constructor(message, code, statusCode = 0, cause) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.cause = cause;
+    this.name = "StorageError";
+  }
+};
+
+// src/mime.ts
+var MIME_MAP = {
+  // Text
+  ".txt": "text/plain",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".css": "text/css",
+  ".csv": "text/csv",
+  ".xml": "text/xml",
+  // Application
+  ".json": "application/json",
+  ".js": "application/javascript",
+  ".mjs": "application/javascript",
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+  ".gz": "application/gzip",
+  ".tar": "application/x-tar",
+  ".yaml": "application/x-yaml",
+  ".yml": "application/x-yaml",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  // Image
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".avif": "image/avif",
+  // Audio/Video
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".ogg": "audio/ogg",
+  // Font
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf"
+};
+var DEFAULT_MIME = "application/octet-stream";
+function detectContentType(key) {
+  const lastDot = key.lastIndexOf(".");
+  if (lastDot === -1) return DEFAULT_MIME;
+  const ext = key.slice(lastDot).toLowerCase();
+  return MIME_MAP[ext] ?? DEFAULT_MIME;
+}
+
+// src/client.ts
+var DEFAULT_PORT = 9e3;
+var DEFAULT_REGION = "us-east-1";
+var DEFAULT_SIGNED_URL_EXPIRY = 3600;
+var StorageClient = class _StorageClient {
+  client;
+  bucket;
+  constructor(config) {
+    if (!config.host) {
+      throw new StorageError("host is required", "INVALID_CONFIG");
+    }
+    if (!config.accessKey) {
+      throw new StorageError("accessKey is required", "INVALID_CONFIG");
+    }
+    if (!config.secretKey) {
+      throw new StorageError("secretKey is required", "INVALID_CONFIG");
+    }
+    if (!config.bucket) {
+      throw new StorageError("bucket is required", "INVALID_CONFIG");
+    }
+    this.bucket = config.bucket;
+    this.client = new import_minio.Client({
+      endPoint: config.host,
+      port: config.port ?? DEFAULT_PORT,
+      useSSL: config.useSSL ?? false,
+      accessKey: config.accessKey,
+      secretKey: config.secretKey,
+      region: config.region ?? DEFAULT_REGION
+    });
+  }
+  /**
+   * Create a StorageClient from environment variables.
+   *
+   * Reads: S3_HOST, S3_PORT, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY,
+   *        S3_REGION, S3_BUCKET
+   */
+  static fromEnv() {
+    const host = process.env.S3_HOST;
+    if (!host) {
+      throw new StorageError(
+        "S3_HOST environment variable is required. Declare storage in catalog-info.yaml to have credentials injected automatically.",
+        "INVALID_CONFIG"
+      );
+    }
+    return new _StorageClient({
+      host,
+      port: process.env.S3_PORT ? parseInt(process.env.S3_PORT, 10) : DEFAULT_PORT,
+      accessKey: process.env.S3_ACCESS_KEY_ID ?? "",
+      secretKey: process.env.S3_SECRET_ACCESS_KEY ?? "",
+      region: process.env.S3_REGION ?? DEFAULT_REGION,
+      bucket: process.env.S3_BUCKET ?? ""
+    });
+  }
+  /**
+   * Create a StorageClient for a named bucket.
+   *
+   * Reads S3_{NAME}_BUCKET for the bucket name, shares
+   * connection config (S3_HOST, etc.) from the environment.
+   */
+  static fromEnvNamed(name) {
+    const envSuffix = name.toUpperCase().replace(/-/g, "_");
+    const bucket = process.env[`S3_${envSuffix}_BUCKET`];
+    if (!bucket) {
+      throw new StorageError(
+        `S3_${envSuffix}_BUCKET environment variable is required. Declare storage with name "${name}" in catalog-info.yaml.`,
+        "INVALID_CONFIG"
+      );
+    }
+    const host = process.env.S3_HOST;
+    if (!host) {
+      throw new StorageError(
+        "S3_HOST environment variable is required.",
+        "INVALID_CONFIG"
+      );
+    }
+    return new _StorageClient({
+      host,
+      port: process.env.S3_PORT ? parseInt(process.env.S3_PORT, 10) : DEFAULT_PORT,
+      accessKey: process.env.S3_ACCESS_KEY_ID ?? "",
+      secretKey: process.env.S3_SECRET_ACCESS_KEY ?? "",
+      region: process.env.S3_REGION ?? DEFAULT_REGION,
+      bucket
+    });
+  }
+  // ─── Core Operations ────────────────────────────────────────────
+  /**
+   * Upload data to the bucket.
+   * Accepts Buffer, string, or Readable stream.
+   * Content-type is auto-detected from the key if not provided.
+   */
+  async upload(key, data, options) {
+    const contentType = options?.contentType ?? detectContentType(key);
+    const metadata = {
+      "Content-Type": contentType,
+      ...options?.metadata ?? {}
+    };
+    try {
+      const input = typeof data === "string" ? Buffer.from(data) : data;
+      await this.client.putObject(this.bucket, key, input, void 0, metadata);
+    } catch (error) {
+      throw this.wrapError("Upload failed", key, error);
+    }
+  }
+  /**
+   * Download an object and return its contents as a Buffer.
+   * For large files, use downloadStream() instead.
+   */
+  async download(key) {
+    try {
+      const stream = await this.client.getObject(this.bucket, key);
+      return await this.streamToBuffer(stream);
+    } catch (error) {
+      throw this.wrapError("Download failed", key, error);
+    }
+  }
+  /**
+   * Download an object as a Readable stream.
+   * Use this for large files to avoid loading everything into memory.
+   */
+  async downloadStream(key) {
+    try {
+      return await this.client.getObject(this.bucket, key);
+    } catch (error) {
+      throw this.wrapError("Download failed", key, error);
+    }
+  }
+  /**
+   * Delete one or more objects.
+   * Accepts a single key or an array of keys for bulk delete.
+   */
+  async delete(keys) {
+    try {
+      const keyArray = typeof keys === "string" ? [keys] : [...keys];
+      if (keyArray.length === 1) {
+        await this.client.removeObject(this.bucket, keyArray[0]);
+      } else {
+        await this.client.removeObjects(
+          this.bucket,
+          keyArray.map((name) => ({ name }))
+        );
+      }
+    } catch (error) {
+      const keyStr = typeof keys === "string" ? keys : `${keys.length} objects`;
+      throw this.wrapError("Delete failed", keyStr, error);
+    }
+  }
+  // ─── Listing & Metadata ─────────────────────────────────────────
+  /**
+   * List objects with an optional prefix.
+   * Returns a complete array (not a stream) for simplicity.
+   */
+  async list(prefix) {
+    try {
+      const stream = this.client.listObjectsV2(this.bucket, prefix ?? "", true);
+      const items = [];
+      return new Promise((resolve, reject) => {
+        stream.on("data", (obj) => {
+          if (obj.name) {
+            items.push({
+              key: obj.name,
+              size: obj.size,
+              etag: obj.etag,
+              lastModified: obj.lastModified
+            });
+          }
+        });
+        stream.on("end", () => resolve(items));
+        stream.on("error", reject);
+      });
+    } catch (error) {
+      throw this.wrapError("List failed", prefix ?? "", error);
+    }
+  }
+  /**
+   * Check if an object exists.
+   */
+  async exists(key) {
+    try {
+      await this.client.statObject(this.bucket, key);
+      return true;
+    } catch (error) {
+      if (this.isNotFoundError(error)) {
+        return false;
+      }
+      throw this.wrapError("Exists check failed", key, error);
+    }
+  }
+  /**
+   * Get object metadata (size, etag, lastModified, contentType).
+   */
+  async stat(key) {
+    try {
+      const result = await this.client.statObject(this.bucket, key);
+      return {
+        size: result.size,
+        etag: result.etag,
+        lastModified: result.lastModified,
+        contentType: result.metaData?.["content-type"] ?? "application/octet-stream"
+      };
+    } catch (error) {
+      throw this.wrapError("Stat failed", key, error);
+    }
+  }
+  // ─── Presigned URLs ─────────────────────────────────────────────
+  /**
+   * Generate a presigned download URL.
+   */
+  async getSignedUrl(key, options) {
+    try {
+      const expiry = options?.expiresIn ?? DEFAULT_SIGNED_URL_EXPIRY;
+      return await this.client.presignedGetObject(this.bucket, key, expiry);
+    } catch (error) {
+      throw this.wrapError("Presign download URL failed", key, error);
+    }
+  }
+  /**
+   * Generate a presigned upload URL (PUT).
+   */
+  async getUploadUrl(key, options) {
+    try {
+      const expiry = options?.expiresIn ?? DEFAULT_SIGNED_URL_EXPIRY;
+      return await this.client.presignedPutObject(this.bucket, key, expiry);
+    } catch (error) {
+      throw this.wrapError("Presign upload URL failed", key, error);
+    }
+  }
+  // ─── Internal Helpers ───────────────────────────────────────────
+  async streamToBuffer(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks);
+  }
+  isNotFoundError(error) {
+    if (error && typeof error === "object") {
+      const err = error;
+      return err.code === "NotFound" || err.code === "NoSuchKey";
+    }
+    return false;
+  }
+  wrapError(action, key, error) {
+    if (error instanceof StorageError) return error;
+    const err = error;
+    const message = err?.message ?? String(error);
+    const s3Code = err?.code;
+    let code = "UNKNOWN";
+    let statusCode = 0;
+    if (s3Code === "NotFound" || s3Code === "NoSuchKey") {
+      code = "NOT_FOUND";
+      statusCode = 404;
+    } else if (s3Code === "AccessDenied" || s3Code === "InvalidAccessKeyId") {
+      code = "ACCESS_DENIED";
+      statusCode = 403;
+    } else if (s3Code === "NoSuchBucket") {
+      code = "BUCKET_NOT_FOUND";
+      statusCode = 404;
+    } else if (s3Code === "ECONNREFUSED" || s3Code === "ENOTFOUND" || s3Code === "ETIMEDOUT") {
+      code = "NETWORK_ERROR";
+    } else if (action.startsWith("Upload")) {
+      code = "UPLOAD_FAILED";
+    } else if (action.startsWith("Delete")) {
+      code = "DELETE_FAILED";
+    } else if (action.startsWith("Presign")) {
+      code = "PRESIGN_FAILED";
+    }
+    return new StorageError(
+      `${action} for "${key}": ${message}`,
+      code,
+      statusCode,
+      error
+    );
+  }
+};
+
+// src/index.ts
+function createStorage(input) {
+  if (input === void 0) {
+    return StorageClient.fromEnv();
+  }
+  if (typeof input === "string") {
+    return StorageClient.fromEnvNamed(input);
+  }
+  return new StorageClient({
+    host: input.host ?? process.env.S3_HOST ?? "",
+    port: input.port ?? (process.env.S3_PORT ? parseInt(process.env.S3_PORT, 10) : void 0),
+    accessKey: input.accessKey ?? process.env.S3_ACCESS_KEY_ID ?? "",
+    secretKey: input.secretKey ?? process.env.S3_SECRET_ACCESS_KEY ?? "",
+    region: input.region ?? process.env.S3_REGION,
+    bucket: input.bucket,
+    useSSL: input.useSSL
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StorageClient,
+  StorageError,
+  createStorage,
+  detectContentType
+});

package/dist/index.mjs

@@ -0,0 +1,364 @@
+// src/client.ts
+import { Client as MinioClient } from "minio";
+
+// src/errors.ts
+var StorageError = class extends Error {
+  constructor(message, code, statusCode = 0, cause) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.cause = cause;
+    this.name = "StorageError";
+  }
+};
+
+// src/mime.ts
+var MIME_MAP = {
+  // Text
+  ".txt": "text/plain",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".css": "text/css",
+  ".csv": "text/csv",
+  ".xml": "text/xml",
+  // Application
+  ".json": "application/json",
+  ".js": "application/javascript",
+  ".mjs": "application/javascript",
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+  ".gz": "application/gzip",
+  ".tar": "application/x-tar",
+  ".yaml": "application/x-yaml",
+  ".yml": "application/x-yaml",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  // Image
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".avif": "image/avif",
+  // Audio/Video
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".ogg": "audio/ogg",
+  // Font
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf"
+};
+var DEFAULT_MIME = "application/octet-stream";
+function detectContentType(key) {
+  const lastDot = key.lastIndexOf(".");
+  if (lastDot === -1) return DEFAULT_MIME;
+  const ext = key.slice(lastDot).toLowerCase();
+  return MIME_MAP[ext] ?? DEFAULT_MIME;
+}
+
+// src/client.ts
+var DEFAULT_PORT = 9e3;
+var DEFAULT_REGION = "us-east-1";
+var DEFAULT_SIGNED_URL_EXPIRY = 3600;
+var StorageClient = class _StorageClient {
+  client;
+  bucket;
+  constructor(config) {
+    if (!config.host) {
+      throw new StorageError("host is required", "INVALID_CONFIG");
+    }
+    if (!config.accessKey) {
+      throw new StorageError("accessKey is required", "INVALID_CONFIG");
+    }
+    if (!config.secretKey) {
+      throw new StorageError("secretKey is required", "INVALID_CONFIG");
+    }
+    if (!config.bucket) {
+      throw new StorageError("bucket is required", "INVALID_CONFIG");
+    }
+    this.bucket = config.bucket;
+    this.client = new MinioClient({
+      endPoint: config.host,
+      port: config.port ?? DEFAULT_PORT,
+      useSSL: config.useSSL ?? false,
+      accessKey: config.accessKey,
+      secretKey: config.secretKey,
+      region: config.region ?? DEFAULT_REGION
+    });
+  }
+  /**
+   * Create a StorageClient from environment variables.
+   *
+   * Reads: S3_HOST, S3_PORT, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY,
+   *        S3_REGION, S3_BUCKET
+   */
+  static fromEnv() {
+    const host = process.env.S3_HOST;
+    if (!host) {
+      throw new StorageError(
+        "S3_HOST environment variable is required. Declare storage in catalog-info.yaml to have credentials injected automatically.",
+        "INVALID_CONFIG"
+      );
+    }
+    return new _StorageClient({
+      host,
+      port: process.env.S3_PORT ? parseInt(process.env.S3_PORT, 10) : DEFAULT_PORT,
+      accessKey: process.env.S3_ACCESS_KEY_ID ?? "",
+      secretKey: process.env.S3_SECRET_ACCESS_KEY ?? "",
+      region: process.env.S3_REGION ?? DEFAULT_REGION,
+      bucket: process.env.S3_BUCKET ?? ""
+    });
+  }
+  /**
+   * Create a StorageClient for a named bucket.
+   *
+   * Reads S3_{NAME}_BUCKET for the bucket name, shares
+   * connection config (S3_HOST, etc.) from the environment.
+   */
+  static fromEnvNamed(name) {
+    const envSuffix = name.toUpperCase().replace(/-/g, "_");
+    const bucket = process.env[`S3_${envSuffix}_BUCKET`];
+    if (!bucket) {
+      throw new StorageError(
+        `S3_${envSuffix}_BUCKET environment variable is required. Declare storage with name "${name}" in catalog-info.yaml.`,
+        "INVALID_CONFIG"
+      );
+    }
+    const host = process.env.S3_HOST;
+    if (!host) {
+      throw new StorageError(
+        "S3_HOST environment variable is required.",
+        "INVALID_CONFIG"
+      );
+    }
+    return new _StorageClient({
+      host,
+      port: process.env.S3_PORT ? parseInt(process.env.S3_PORT, 10) : DEFAULT_PORT,
+      accessKey: process.env.S3_ACCESS_KEY_ID ?? "",
+      secretKey: process.env.S3_SECRET_ACCESS_KEY ?? "",
+      region: process.env.S3_REGION ?? DEFAULT_REGION,
+      bucket
+    });
+  }
+  // ─── Core Operations ────────────────────────────────────────────
+  /**
+   * Upload data to the bucket.
+   * Accepts Buffer, string, or Readable stream.
+   * Content-type is auto-detected from the key if not provided.
+   */
+  async upload(key, data, options) {
+    const contentType = options?.contentType ?? detectContentType(key);
+    const metadata = {
+      "Content-Type": contentType,
+      ...options?.metadata ?? {}
+    };
+    try {
+      const input = typeof data === "string" ? Buffer.from(data) : data;
+      await this.client.putObject(this.bucket, key, input, void 0, metadata);
+    } catch (error) {
+      throw this.wrapError("Upload failed", key, error);
+    }
+  }
+  /**
+   * Download an object and return its contents as a Buffer.
+   * For large files, use downloadStream() instead.
+   */
+  async download(key) {
+    try {
+      const stream = await this.client.getObject(this.bucket, key);
+      return await this.streamToBuffer(stream);
+    } catch (error) {
+      throw this.wrapError("Download failed", key, error);
+    }
+  }
+  /**
+   * Download an object as a Readable stream.
+   * Use this for large files to avoid loading everything into memory.
+   */
+  async downloadStream(key) {
+    try {
+      return await this.client.getObject(this.bucket, key);
+    } catch (error) {
+      throw this.wrapError("Download failed", key, error);
+    }
+  }
+  /**
+   * Delete one or more objects.
+   * Accepts a single key or an array of keys for bulk delete.
+   */
+  async delete(keys) {
+    try {
+      const keyArray = typeof keys === "string" ? [keys] : [...keys];
+      if (keyArray.length === 1) {
+        await this.client.removeObject(this.bucket, keyArray[0]);
+      } else {
+        await this.client.removeObjects(
+          this.bucket,
+          keyArray.map((name) => ({ name }))
+        );
+      }
+    } catch (error) {
+      const keyStr = typeof keys === "string" ? keys : `${keys.length} objects`;
+      throw this.wrapError("Delete failed", keyStr, error);
+    }
+  }
+  // ─── Listing & Metadata ─────────────────────────────────────────
+  /**
+   * List objects with an optional prefix.
+   * Returns a complete array (not a stream) for simplicity.
+   */
+  async list(prefix) {
+    try {
+      const stream = this.client.listObjectsV2(this.bucket, prefix ?? "", true);
+      const items = [];
+      return new Promise((resolve, reject) => {
+        stream.on("data", (obj) => {
+          if (obj.name) {
+            items.push({
+              key: obj.name,
+              size: obj.size,
+              etag: obj.etag,
+              lastModified: obj.lastModified
+            });
+          }
+        });
+        stream.on("end", () => resolve(items));
+        stream.on("error", reject);
+      });
+    } catch (error) {
+      throw this.wrapError("List failed", prefix ?? "", error);
+    }
+  }
+  /**
+   * Check if an object exists.
+   */
+  async exists(key) {
+    try {
+      await this.client.statObject(this.bucket, key);
+      return true;
+    } catch (error) {
+      if (this.isNotFoundError(error)) {
+        return false;
+      }
+      throw this.wrapError("Exists check failed", key, error);
+    }
+  }
+  /**
+   * Get object metadata (size, etag, lastModified, contentType).
+   */
+  async stat(key) {
+    try {
+      const result = await this.client.statObject(this.bucket, key);
+      return {
+        size: result.size,
+        etag: result.etag,
+        lastModified: result.lastModified,
+        contentType: result.metaData?.["content-type"] ?? "application/octet-stream"
+      };
+    } catch (error) {
+      throw this.wrapError("Stat failed", key, error);
+    }
+  }
+  // ─── Presigned URLs ─────────────────────────────────────────────
+  /**
+   * Generate a presigned download URL.
+   */
+  async getSignedUrl(key, options) {
+    try {
+      const expiry = options?.expiresIn ?? DEFAULT_SIGNED_URL_EXPIRY;
+      return await this.client.presignedGetObject(this.bucket, key, expiry);
+    } catch (error) {
+      throw this.wrapError("Presign download URL failed", key, error);
+    }
+  }
+  /**
+   * Generate a presigned upload URL (PUT).
+   */
+  async getUploadUrl(key, options) {
+    try {
+      const expiry = options?.expiresIn ?? DEFAULT_SIGNED_URL_EXPIRY;
+      return await this.client.presignedPutObject(this.bucket, key, expiry);
+    } catch (error) {
+      throw this.wrapError("Presign upload URL failed", key, error);
+    }
+  }
+  // ─── Internal Helpers ───────────────────────────────────────────
+  async streamToBuffer(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks);
+  }
+  isNotFoundError(error) {
+    if (error && typeof error === "object") {
+      const err = error;
+      return err.code === "NotFound" || err.code === "NoSuchKey";
+    }
+    return false;
+  }
+  wrapError(action, key, error) {
+    if (error instanceof StorageError) return error;
+    const err = error;
+    const message = err?.message ?? String(error);
+    const s3Code = err?.code;
+    let code = "UNKNOWN";
+    let statusCode = 0;
+    if (s3Code === "NotFound" || s3Code === "NoSuchKey") {
+      code = "NOT_FOUND";
+      statusCode = 404;
+    } else if (s3Code === "AccessDenied" || s3Code === "InvalidAccessKeyId") {
+      code = "ACCESS_DENIED";
+      statusCode = 403;
+    } else if (s3Code === "NoSuchBucket") {
+      code = "BUCKET_NOT_FOUND";
+      statusCode = 404;
+    } else if (s3Code === "ECONNREFUSED" || s3Code === "ENOTFOUND" || s3Code === "ETIMEDOUT") {
+      code = "NETWORK_ERROR";
+    } else if (action.startsWith("Upload")) {
+      code = "UPLOAD_FAILED";
+    } else if (action.startsWith("Delete")) {
+      code = "DELETE_FAILED";
+    } else if (action.startsWith("Presign")) {
+      code = "PRESIGN_FAILED";
+    }
+    return new StorageError(
+      `${action} for "${key}": ${message}`,
+      code,
+      statusCode,
+      error
+    );
+  }
+};
+
+// src/index.ts
+function createStorage(input) {
+  if (input === void 0) {
+    return StorageClient.fromEnv();
+  }
+  if (typeof input === "string") {
+    return StorageClient.fromEnvNamed(input);
+  }
+  return new StorageClient({
+    host: input.host ?? process.env.S3_HOST ?? "",
+    port: input.port ?? (process.env.S3_PORT ? parseInt(process.env.S3_PORT, 10) : void 0),
+    accessKey: input.accessKey ?? process.env.S3_ACCESS_KEY_ID ?? "",
+    secretKey: input.secretKey ?? process.env.S3_SECRET_ACCESS_KEY ?? "",
+    region: input.region ?? process.env.S3_REGION,
+    bucket: input.bucket,
+    useSSL: input.useSSL
+  });
+}
+export {
+  StorageClient,
+  StorageError,
+  createStorage,
+  detectContentType
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "tawa-storage",
+  "version": "0.1.0",
+  "description": "S3-compatible object storage SDK for the Tawa platform",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "publish:npm": "npm publish --access public",
+    "publish:forgejo": "npm publish --registry https://git.insureco.io/api/packages/insureco/npm/"
+  },
+  "keywords": [
+    "tawa",
+    "storage",
+    "s3",
+    "minio",
+    "object-storage",
+    "insureco"
+  ],
+  "author": "InsurEco",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://git.insureco.io/insureco/tawa-storage"
+  },
+  "dependencies": {
+    "minio": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}