@maroonedsoftware/storage 0.1.0 → 0.2.0

package/dist/disk.storage.provider.d.ts

@@ -0,0 +1,57 @@
+import { Readable } from 'node:stream';
+import type { SignedUrlOptions, StorageListOptions, StorageListResult, StorageObjectMetadata, StorageReadOptions, StorageWriteOptions } from './storage.provider.js';
+import { StorageProvider } from './storage.provider.js';
+/**
+ * Construction options for {@link DiskStorageProvider}.
+ *
+ * A class (not an interface) so it can serve as an InjectKit token — register
+ * an instance and the container can construct {@link DiskStorageProvider}.
+ */
+export declare class DiskStorageProviderOptions {
+    /** Root directory the provider stores objects under. */
+    readonly rootDir: string;
+    /**
+     * Base URL objects are publicly served from. When set, {@link DiskStorageProvider.getSignedUrl}
+     * returns `${publicBaseUrl}/${key}`; when omitted, signing is unsupported.
+     */
+    readonly publicBaseUrl?: string;
+    constructor(init: {
+        rootDir: string;
+        publicBaseUrl?: string;
+    });
+}
+/**
+ * {@link StorageProvider} backed by the local filesystem rooted at a directory.
+ *
+ * Keys map to paths under the root; nested keys create intermediate directories
+ * on write. User metadata is not persisted (the filesystem has no native slot),
+ * and `getSignedUrl` requires a configured `publicBaseUrl`. Useful for local
+ * development and as an in-process test double.
+ */
+export declare class DiskStorageProvider extends StorageProvider {
+    private readonly options;
+    constructor(options: DiskStorageProviderOptions);
+    write(key: string, body: Readable | Buffer | string, _options?: StorageWriteOptions): Promise<void>;
+    read(key: string, options?: StorageReadOptions): Promise<Readable>;
+    stat(key: string): Promise<StorageObjectMetadata>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    copy(sourceKey: string, destinationKey: string): Promise<void>;
+    move(sourceKey: string, destinationKey: string): Promise<void>;
+    /**
+     * Lists objects under the root, optionally filtered by prefix.
+     *
+     * Note: this walks the entire directory tree and `stat`s every matching file
+     * on each call — pagination slices an in-memory list, it does not make paging
+     * cheaper. Fine for development and modest trees (its intended use); avoid
+     * pointing it at very large directories.
+     */
+    list(options?: StorageListOptions): Promise<StorageListResult>;
+    getSignedUrl(key: string, _options: SignedUrlOptions): Promise<string>;
+    /** Resolve a key to an absolute path, rejecting traversal that escapes the root. */
+    private resolveKey;
+    private assertExists;
+    /** Recursively collect file keys (root-relative, `/`-separated) under `dir`. */
+    private walk;
+}
+//# sourceMappingURL=disk.storage.provider.d.ts.map

package/dist/disk.storage.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk.storage.provider.d.ts","sourceRoot":"","sources":["../src/disk.storage.provider.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvC,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;GAKG;AACH,qBAAa,0BAA0B;IACrC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;gBAEpB,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE;CAI9D;AAED;;;;;;;GAOG;AACH,qBACa,mBAAoB,SAAQ,eAAe;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,0BAA0B;IAI1D,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAOlE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAYjD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAerC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9D,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBpE;;;;;;;OAOG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAoB9D,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAe5E,oFAAoF;IACpF,OAAO,CAAC,UAAU;YASJ,YAAY;IAkB1B,gFAAgF;YAClE,IAAI;CAWnB"}

package/dist/gcs.storage.provider.d.ts

@@ -0,0 +1,37 @@
+import { Readable } from 'node:stream';
+import type { Storage } from '@google-cloud/storage';
+import type { SignedUrlOptions, StorageListOptions, StorageListResult, StorageObjectMetadata, StorageReadOptions, StorageWriteOptions } from './storage.provider.js';
+import { StorageProvider } from './storage.provider.js';
+/**
+ * Construction options for {@link GcsStorageProvider}.
+ *
+ * A class (not an interface) so it can serve as an InjectKit token — register
+ * an instance and the container can construct {@link GcsStorageProvider}.
+ */
+export declare class GcsStorageProviderOptions {
+    /** Name of the bucket all keys live in. */
+    readonly bucket: string;
+    constructor(init: {
+        bucket: string;
+    });
+}
+/**
+ * {@link StorageProvider} backed by a Google Cloud Storage bucket.
+ */
+export declare class GcsStorageProvider extends StorageProvider {
+    private readonly client;
+    private readonly options;
+    constructor(client: Storage, options: GcsStorageProviderOptions);
+    write(key: string, body: Readable | Buffer | string, options?: StorageWriteOptions): Promise<void>;
+    read(key: string, options?: StorageReadOptions): Promise<Readable>;
+    stat(key: string): Promise<StorageObjectMetadata>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    copy(sourceKey: string, destinationKey: string): Promise<void>;
+    move(sourceKey: string, destinationKey: string): Promise<void>;
+    list(options?: StorageListOptions): Promise<StorageListResult>;
+    getSignedUrl(key: string, options: SignedUrlOptions): Promise<string>;
+    private file;
+    private mapError;
+}
+//# sourceMappingURL=gcs.storage.provider.d.ts.map

package/dist/gcs.storage.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcs.storage.provider.d.ts","sourceRoot":"","sources":["../src/gcs.storage.provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,OAAO,KAAK,EAAQ,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;GAKG;AACH,qBAAa,yBAAyB;IACpC,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE;CAGrC;AAED;;GAEG;AACH,qBACa,kBAAmB,SAAQ,eAAe;IAEnD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,yBAAyB;IAK/C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBlG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAWlE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAgBjD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWrC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9D,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9D,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAsB9D,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAU3E,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,QAAQ;CASjB"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './storage.provider.js';
+export * from './storage.errors.js';
+export * from './disk.storage.provider.js';
+export * from './s3.storage.provider.js';
+export * from './gcs.storage.provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,672 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/storage.provider.ts
+import { Injectable } from "injectkit";
+function _ts_decorate(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+var StorageProvider = class {
+  static {
+    __name(this, "StorageProvider");
+  }
+};
+StorageProvider = _ts_decorate([
+  Injectable()
+], StorageProvider);
+
+// src/storage.errors.ts
+import { ServerkitError } from "@maroonedsoftware/errors";
+var StorageError = class extends ServerkitError {
+  static {
+    __name(this, "StorageError");
+  }
+  constructor(message, options) {
+    super(message, options);
+    this.name = "StorageError";
+  }
+};
+var StorageObjectNotFoundError = class extends StorageError {
+  static {
+    __name(this, "StorageObjectNotFoundError");
+  }
+  key;
+  constructor(key, options) {
+    super(`storage object '${key}' not found`, options), this.key = key;
+    this.name = "StorageObjectNotFoundError";
+  }
+};
+var StorageAccessDeniedError = class extends StorageError {
+  static {
+    __name(this, "StorageAccessDeniedError");
+  }
+  key;
+  constructor(key, options) {
+    super(`access denied for storage object '${key}'`, options), this.key = key;
+    this.name = "StorageAccessDeniedError";
+  }
+};
+var StorageOperationNotSupportedError = class extends StorageError {
+  static {
+    __name(this, "StorageOperationNotSupportedError");
+  }
+  constructor(operation, options) {
+    super(`storage operation '${operation}' is not supported by this backend`, options);
+    this.name = "StorageOperationNotSupportedError";
+  }
+};
+
+// src/disk.storage.provider.ts
+import { Injectable as Injectable2 } from "injectkit";
+import { createReadStream, createWriteStream } from "fs";
+import { copyFile, mkdir, readdir, rename, rm, stat as fsStat, unlink } from "fs/promises";
+import { dirname, join, posix, relative, resolve, sep } from "path";
+import { pipeline } from "stream/promises";
+import { Readable } from "stream";
+import { DateTime } from "luxon";
+import mime from "mime-types";
+function _ts_decorate2(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
+function _ts_metadata(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata, "_ts_metadata");
+var DiskStorageProviderOptions = class {
+  static {
+    __name(this, "DiskStorageProviderOptions");
+  }
+  /** Root directory the provider stores objects under. */
+  rootDir;
+  /**
+  * Base URL objects are publicly served from. When set, {@link DiskStorageProvider.getSignedUrl}
+  * returns `${publicBaseUrl}/${key}`; when omitted, signing is unsupported.
+  */
+  publicBaseUrl;
+  constructor(init) {
+    this.rootDir = init.rootDir;
+    this.publicBaseUrl = init.publicBaseUrl;
+  }
+};
+var DiskStorageProvider = class extends StorageProvider {
+  static {
+    __name(this, "DiskStorageProvider");
+  }
+  options;
+  constructor(options) {
+    super(), this.options = options;
+  }
+  async write(key, body, _options) {
+    const path = this.resolveKey(key);
+    await mkdir(dirname(path), {
+      recursive: true
+    });
+    const source = body instanceof Readable ? body : Readable.from(body instanceof Buffer ? body : Buffer.from(body));
+    await pipeline(source, createWriteStream(path));
+  }
+  async read(key, options) {
+    const path = this.resolveKey(key);
+    await this.assertExists(key, path);
+    return options?.range ? createReadStream(path, {
+      start: options.range.start,
+      end: options.range.end
+    }) : createReadStream(path);
+  }
+  async stat(key) {
+    const path = this.resolveKey(key);
+    const stats = await this.assertExists(key, path);
+    const contentType = mime.lookup(path);
+    return {
+      key,
+      size: stats.size,
+      contentType: contentType === false ? void 0 : contentType,
+      lastModified: DateTime.fromJSDate(stats.mtime)
+    };
+  }
+  async exists(key) {
+    try {
+      const stats = await fsStat(this.resolveKey(key));
+      return stats.isFile();
+    } catch (error) {
+      if (isNotFound(error)) {
+        return false;
+      }
+      if (isAccessDenied(error)) {
+        throw new StorageAccessDeniedError(key, {
+          cause: error
+        });
+      }
+      throw error;
+    }
+  }
+  async delete(key) {
+    await rm(this.resolveKey(key), {
+      force: true
+    });
+  }
+  async copy(sourceKey, destinationKey) {
+    const source = this.resolveKey(sourceKey);
+    const destination = this.resolveKey(destinationKey);
+    await this.assertExists(sourceKey, source);
+    await mkdir(dirname(destination), {
+      recursive: true
+    });
+    await copyFile(source, destination);
+  }
+  async move(sourceKey, destinationKey) {
+    const source = this.resolveKey(sourceKey);
+    const destination = this.resolveKey(destinationKey);
+    await this.assertExists(sourceKey, source);
+    await mkdir(dirname(destination), {
+      recursive: true
+    });
+    try {
+      await rename(source, destination);
+    } catch (error) {
+      if (typeof error === "object" && error !== null && error.code === "EXDEV") {
+        await copyFile(source, destination);
+        await unlink(source);
+        return;
+      }
+      throw error;
+    }
+  }
+  /**
+  * Lists objects under the root, optionally filtered by prefix.
+  *
+  * Note: this walks the entire directory tree and `stat`s every matching file
+  * on each call — pagination slices an in-memory list, it does not make paging
+  * cheaper. Fine for development and modest trees (its intended use); avoid
+  * pointing it at very large directories.
+  */
+  async list(options) {
+    const prefix = options?.prefix ?? "";
+    const keys = [];
+    await this.walk(this.options.rootDir, keys);
+    const matched = keys.filter((key) => key.startsWith(prefix)).sort();
+    const start = options?.cursor ? matched.findIndex((key) => key > options.cursor) : 0;
+    const from = start === -1 ? matched.length : start;
+    const limit = options?.limit ?? matched.length;
+    const page = matched.slice(from, from + limit);
+    const objects = await Promise.all(page.map((key) => this.stat(key)));
+    const hasMore = from + limit < matched.length;
+    return {
+      objects,
+      cursor: hasMore && page.length > 0 ? page[page.length - 1] : void 0
+    };
+  }
+  async getSignedUrl(key, _options) {
+    if (!this.options.publicBaseUrl) {
+      throw new StorageOperationNotSupportedError("getSignedUrl");
+    }
+    this.resolveKey(key);
+    const encodedPath = key.replace(/^\/+/, "").split("/").map(encodeURIComponent).join("/");
+    return `${this.options.publicBaseUrl.replace(/\/+$/, "")}/${encodedPath}`;
+  }
+  /** Resolve a key to an absolute path, rejecting traversal that escapes the root. */
+  resolveKey(key) {
+    const path = resolve(this.options.rootDir, key);
+    const rel = relative(this.options.rootDir, path);
+    if (rel === "" || rel.startsWith("..") || rel.startsWith(`..${sep}`)) {
+      throw new StorageOperationNotSupportedError(`key '${key}' resolves outside the storage root`);
+    }
+    return path;
+  }
+  async assertExists(key, path) {
+    try {
+      const stats = await fsStat(path);
+      if (!stats.isFile()) {
+        throw new StorageObjectNotFoundError(key);
+      }
+      return stats;
+    } catch (error) {
+      if (isNotFound(error)) {
+        throw new StorageObjectNotFoundError(key, {
+          cause: error
+        });
+      }
+      if (isAccessDenied(error)) {
+        throw new StorageAccessDeniedError(key, {
+          cause: error
+        });
+      }
+      throw error;
+    }
+  }
+  /** Recursively collect file keys (root-relative, `/`-separated) under `dir`. */
+  async walk(dir, into) {
+    const entries = await readdir(dir, {
+      withFileTypes: true
+    });
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await this.walk(full, into);
+      } else if (entry.isFile()) {
+        into.push(relative(this.options.rootDir, full).split(sep).join(posix.sep));
+      }
+    }
+  }
+};
+DiskStorageProvider = _ts_decorate2([
+  Injectable2(),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof DiskStorageProviderOptions === "undefined" ? Object : DiskStorageProviderOptions
+  ])
+], DiskStorageProvider);
+function isNotFound(error) {
+  return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+__name(isNotFound, "isNotFound");
+function isAccessDenied(error) {
+  if (typeof error !== "object" || error === null) {
+    return false;
+  }
+  const code = error.code;
+  return code === "EACCES" || code === "EPERM";
+}
+__name(isAccessDenied, "isAccessDenied");
+
+// src/s3.storage.provider.ts
+import { Injectable as Injectable3 } from "injectkit";
+import { Readable as Readable2 } from "stream";
+import { DateTime as DateTime2 } from "luxon";
+import { CopyObjectCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand } from "@aws-sdk/client-s3";
+import { Upload } from "@aws-sdk/lib-storage";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+function _ts_decorate3(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate3, "_ts_decorate");
+function _ts_metadata2(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata2, "_ts_metadata");
+var S3StorageProviderOptions = class {
+  static {
+    __name(this, "S3StorageProviderOptions");
+  }
+  /** Name of the bucket all keys live in. */
+  bucket;
+  constructor(init) {
+    this.bucket = init.bucket;
+  }
+};
+var S3StorageProvider = class extends StorageProvider {
+  static {
+    __name(this, "S3StorageProvider");
+  }
+  client;
+  options;
+  constructor(client, options) {
+    super(), this.client = client, this.options = options;
+  }
+  async write(key, body, options) {
+    const shared = {
+      Bucket: this.options.bucket,
+      Key: key,
+      ContentType: options?.contentType,
+      ContentLength: options?.contentLength,
+      CacheControl: options?.cacheControl,
+      Metadata: options?.metadata
+    };
+    if (body instanceof Readable2) {
+      const upload = new Upload({
+        client: this.client,
+        params: {
+          ...shared,
+          Body: body
+        }
+      });
+      await upload.done();
+      return;
+    }
+    await this.client.send(new PutObjectCommand({
+      ...shared,
+      Body: body
+    }));
+  }
+  async read(key, options) {
+    try {
+      const response = await this.client.send(new GetObjectCommand({
+        Bucket: this.options.bucket,
+        Key: key,
+        Range: toRangeHeader(options?.range)
+      }));
+      return response.Body;
+    } catch (error) {
+      throw this.mapError(key, error);
+    }
+  }
+  async stat(key) {
+    try {
+      const head = await this.client.send(new HeadObjectCommand({
+        Bucket: this.options.bucket,
+        Key: key
+      }));
+      return {
+        key,
+        size: head.ContentLength ?? 0,
+        contentType: head.ContentType,
+        etag: head.ETag,
+        lastModified: head.LastModified ? DateTime2.fromJSDate(head.LastModified) : void 0,
+        metadata: head.Metadata
+      };
+    } catch (error) {
+      throw this.mapError(key, error);
+    }
+  }
+  async exists(key) {
+    try {
+      await this.client.send(new HeadObjectCommand({
+        Bucket: this.options.bucket,
+        Key: key
+      }));
+      return true;
+    } catch (error) {
+      if (isNotFound2(error)) {
+        return false;
+      }
+      throw this.mapError(key, error);
+    }
+  }
+  async delete(key) {
+    await this.client.send(new DeleteObjectCommand({
+      Bucket: this.options.bucket,
+      Key: key
+    }));
+  }
+  /**
+  * Server-side copy via `CopyObjectCommand`.
+  *
+  * Note: S3's single-request `CopyObject` is capped at 5 GB. Copying a larger
+  * object requires a multipart copy (`UploadPartCopy`), which this provider
+  * does not yet implement — such copies will fail. {@link move} inherits the
+  * same limit since it delegates to `copy`.
+  */
+  async copy(sourceKey, destinationKey) {
+    try {
+      await this.client.send(new CopyObjectCommand({
+        Bucket: this.options.bucket,
+        Key: destinationKey,
+        // CopySource must be the URL-encoded `bucket/key` of the source object.
+        CopySource: `${this.options.bucket}/${encodeURIComponent(sourceKey)}`
+      }));
+    } catch (error) {
+      throw this.mapError(sourceKey, error);
+    }
+  }
+  async move(sourceKey, destinationKey) {
+    await this.copy(sourceKey, destinationKey);
+    await this.delete(sourceKey);
+  }
+  async list(options) {
+    const response = await this.client.send(new ListObjectsV2Command({
+      Bucket: this.options.bucket,
+      Prefix: options?.prefix,
+      MaxKeys: options?.limit,
+      ContinuationToken: options?.cursor
+    }));
+    const objects = (response.Contents ?? []).map((item) => ({
+      key: item.Key ?? "",
+      size: item.Size ?? 0,
+      etag: item.ETag,
+      lastModified: item.LastModified ? DateTime2.fromJSDate(item.LastModified) : void 0
+    }));
+    return {
+      objects,
+      cursor: response.IsTruncated ? response.NextContinuationToken : void 0
+    };
+  }
+  async getSignedUrl(key, options) {
+    const command = options.operation === "write" ? new PutObjectCommand({
+      Bucket: this.options.bucket,
+      Key: key,
+      ContentType: options.contentType
+    }) : new GetObjectCommand({
+      Bucket: this.options.bucket,
+      Key: key
+    });
+    return getSignedUrl(this.client, command, {
+      expiresIn: Math.round(options.expiresIn.as("seconds"))
+    });
+  }
+  mapError(key, error) {
+    if (isNotFound2(error)) {
+      return new StorageObjectNotFoundError(key, {
+        cause: error
+      });
+    }
+    if (isAccessDenied2(error)) {
+      return new StorageAccessDeniedError(key, {
+        cause: error
+      });
+    }
+    return error;
+  }
+};
+S3StorageProvider = _ts_decorate3([
+  Injectable3(),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof S3Client === "undefined" ? Object : S3Client,
+    typeof S3StorageProviderOptions === "undefined" ? Object : S3StorageProviderOptions
+  ])
+], S3StorageProvider);
+function errorName(error) {
+  return typeof error === "object" && error !== null ? error.name : void 0;
+}
+__name(errorName, "errorName");
+function statusCode(error) {
+  return typeof error === "object" && error !== null ? error.$metadata?.httpStatusCode : void 0;
+}
+__name(statusCode, "statusCode");
+function isNotFound2(error) {
+  const name = errorName(error);
+  return name === "NoSuchKey" || name === "NotFound" || statusCode(error) === 404;
+}
+__name(isNotFound2, "isNotFound");
+function isAccessDenied2(error) {
+  return errorName(error) === "AccessDenied" || statusCode(error) === 403;
+}
+__name(isAccessDenied2, "isAccessDenied");
+function toRangeHeader(range) {
+  return range ? `bytes=${range.start}-${range.end ?? ""}` : void 0;
+}
+__name(toRangeHeader, "toRangeHeader");
+
+// src/gcs.storage.provider.ts
+import { Injectable as Injectable4 } from "injectkit";
+import { Readable as Readable3 } from "stream";
+import { pipeline as pipeline2 } from "stream/promises";
+import { DateTime as DateTime3 } from "luxon";
+function _ts_decorate4(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate4, "_ts_decorate");
+function _ts_metadata3(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata3, "_ts_metadata");
+var GcsStorageProviderOptions = class {
+  static {
+    __name(this, "GcsStorageProviderOptions");
+  }
+  /** Name of the bucket all keys live in. */
+  bucket;
+  constructor(init) {
+    this.bucket = init.bucket;
+  }
+};
+var GcsStorageProvider = class extends StorageProvider {
+  static {
+    __name(this, "GcsStorageProvider");
+  }
+  client;
+  options;
+  constructor(client, options) {
+    super(), this.client = client, this.options = options;
+  }
+  async write(key, body, options) {
+    const file = this.file(key);
+    const metadata = {
+      contentType: options?.contentType,
+      cacheControl: options?.cacheControl,
+      metadata: options?.metadata
+    };
+    if (body instanceof Readable3) {
+      await pipeline2(body, file.createWriteStream({
+        metadata
+      }));
+      return;
+    }
+    await file.save(body instanceof Buffer ? body : Buffer.from(body), {
+      metadata
+    });
+  }
+  async read(key, options) {
+    const exists = await this.exists(key);
+    if (!exists) {
+      throw new StorageObjectNotFoundError(key);
+    }
+    return this.file(key).createReadStream(options?.range ? {
+      start: options.range.start,
+      end: options.range.end
+    } : void 0);
+  }
+  async stat(key) {
+    try {
+      const [metadata] = await this.file(key).getMetadata();
+      return {
+        key,
+        size: typeof metadata.size === "string" ? Number(metadata.size) : metadata.size ?? 0,
+        contentType: metadata.contentType,
+        etag: metadata.etag,
+        lastModified: metadata.updated ? DateTime3.fromISO(metadata.updated) : void 0,
+        metadata: metadata.metadata
+      };
+    } catch (error) {
+      throw this.mapError(key, error);
+    }
+  }
+  async exists(key) {
+    try {
+      const [exists] = await this.file(key).exists();
+      return exists;
+    } catch (error) {
+      throw this.mapError(key, error);
+    }
+  }
+  async delete(key) {
+    await this.file(key).delete({
+      ignoreNotFound: true
+    });
+  }
+  async copy(sourceKey, destinationKey) {
+    try {
+      await this.file(sourceKey).copy(this.file(destinationKey));
+    } catch (error) {
+      throw this.mapError(sourceKey, error);
+    }
+  }
+  async move(sourceKey, destinationKey) {
+    try {
+      await this.file(sourceKey).move(this.file(destinationKey));
+    } catch (error) {
+      throw this.mapError(sourceKey, error);
+    }
+  }
+  async list(options) {
+    const [files, nextQuery] = await this.client.bucket(this.options.bucket).getFiles({
+      prefix: options?.prefix,
+      maxResults: options?.limit,
+      pageToken: options?.cursor,
+      autoPaginate: false
+    });
+    const objects = files.map((file) => ({
+      key: file.name,
+      size: typeof file.metadata.size === "string" ? Number(file.metadata.size) : file.metadata.size ?? 0,
+      contentType: file.metadata.contentType,
+      etag: file.metadata.etag,
+      lastModified: file.metadata.updated ? DateTime3.fromISO(file.metadata.updated) : void 0
+    }));
+    return {
+      objects,
+      cursor: nextQuery?.pageToken
+    };
+  }
+  async getSignedUrl(key, options) {
+    const [url] = await this.file(key).getSignedUrl({
+      version: "v4",
+      action: options.operation === "write" ? "write" : "read",
+      expires: DateTime3.now().plus(options.expiresIn).toMillis(),
+      contentType: options.operation === "write" ? options.contentType : void 0
+    });
+    return url;
+  }
+  file(key) {
+    return this.client.bucket(this.options.bucket).file(key);
+  }
+  mapError(key, error) {
+    if (isNotFound3(error)) {
+      return new StorageObjectNotFoundError(key, {
+        cause: error
+      });
+    }
+    if (isAccessDenied3(error)) {
+      return new StorageAccessDeniedError(key, {
+        cause: error
+      });
+    }
+    return error;
+  }
+};
+GcsStorageProvider = _ts_decorate4([
+  Injectable4(),
+  _ts_metadata3("design:type", Function),
+  _ts_metadata3("design:paramtypes", [
+    typeof Storage === "undefined" ? Object : Storage,
+    typeof GcsStorageProviderOptions === "undefined" ? Object : GcsStorageProviderOptions
+  ])
+], GcsStorageProvider);
+function statusCode2(error) {
+  return typeof error === "object" && error !== null ? error.code : void 0;
+}
+__name(statusCode2, "statusCode");
+function isNotFound3(error) {
+  return statusCode2(error) === 404;
+}
+__name(isNotFound3, "isNotFound");
+function isAccessDenied3(error) {
+  return statusCode2(error) === 403;
+}
+__name(isAccessDenied3, "isAccessDenied");
+export {
+  DiskStorageProvider,
+  DiskStorageProviderOptions,
+  GcsStorageProvider,
+  GcsStorageProviderOptions,
+  S3StorageProvider,
+  S3StorageProviderOptions,
+  StorageAccessDeniedError,
+  StorageError,
+  StorageObjectNotFoundError,
+  StorageOperationNotSupportedError,
+  StorageProvider
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/storage.provider.ts","../src/storage.errors.ts","../src/disk.storage.provider.ts","../src/s3.storage.provider.ts","../src/gcs.storage.provider.ts"],"sourcesContent":["import { Injectable } from 'injectkit';\nimport { Readable } from 'node:stream';\nimport { DateTime, Duration } from 'luxon';\n\n/**\n * Options applied when writing an object. All fields are optional; backends\n * that cannot honour a given field ignore it (documented per provider).\n */\nexport interface StorageWriteOptions {\n  /** MIME type stored alongside the object (e.g. `image/png`). */\n  contentType?: string;\n  /** Byte length of the body, when known ahead of time. */\n  contentLength?: number;\n  /** `Cache-Control` header persisted with the object (cloud backends). */\n  cacheControl?: string;\n  /** Arbitrary user metadata. Unsupported on the disk backend (ignored). */\n  metadata?: Record<string, string>;\n}\n\n/**\n * Options for {@link StorageProvider.read}.\n */\nexport interface StorageReadOptions {\n  /**\n   * Restrict the read to a byte range. `start` and `end` are both inclusive\n   * (HTTP `Range` semantics); omit `end` to read from `start` to the end of the\n   * object. Useful for media streaming and resumable downloads.\n   */\n  range?: { start: number; end?: number };\n}\n\n/**\n * Metadata describing a stored object, returned by {@link StorageProvider.stat}\n * and {@link StorageProvider.list}.\n */\nexport interface StorageObjectMetadata {\n  /** The object's key. */\n  key: string;\n  /** Size in bytes. */\n  size: number;\n  /** MIME type, when known. */\n  contentType?: string;\n  /** Backend entity tag, when provided. */\n  etag?: string;\n  /** Last modification time, when known. */\n  lastModified?: DateTime;\n  /** User metadata, when the backend supports and returns it. */\n  metadata?: Record<string, string>;\n}\n\n/**\n * Options for {@link StorageProvider.list}.\n */\nexport interface StorageListOptions {\n  /** Restrict results to keys beginning with this prefix. */\n  prefix?: string;\n  /** Maximum number of objects to return in this page. */\n  limit?: number;\n  /** Opaque continuation token from a previous {@link StorageListResult}. */\n  cursor?: string;\n}\n\n/**\n * A single page of {@link StorageProvider.list} results.\n */\nexport interface StorageListResult {\n  /** Objects in this page. */\n  objects: StorageObjectMetadata[];\n  /** Continuation token for the next page, or `undefined` when exhausted. */\n  cursor?: string;\n}\n\n/** Whether a signed URL grants read (download) or write (upload) access. */\nexport type SignedUrlOperation = 'read' | 'write';\n\n/**\n * Options for {@link StorageProvider.getSignedUrl}.\n */\nexport interface SignedUrlOptions {\n  /** The operation the URL authorises. */\n  operation: SignedUrlOperation;\n  /** How long the URL remains valid. */\n  expiresIn: Duration;\n  /** Content type the client must use when uploading (`write` URLs). */\n  contentType?: string;\n}\n\n/**\n * Backend-agnostic object storage. Implementations wrap a concrete backend\n * (local disk, AWS S3, Google Cloud Storage). Bind a concrete provider to this\n * token in the DI container so consumers depend only on the abstraction:\n *\n * ```ts\n * container.bind(StorageProvider).toConstantValue(new DiskStorageProvider({ rootDir: '/var/data' }));\n * ```\n *\n * Keys are hierarchical, `/`-separated paths (e.g. `users/42/avatar.png`), not\n * flat filenames.\n *\n * ## Behaviour contract\n * - {@link read} / {@link stat} on a missing key throw `StorageObjectNotFoundError`.\n * - {@link exists} never throws for a missing key — it returns `false`.\n * - Operations that hit a permission failure throw `StorageAccessDeniedError`.\n * - {@link delete} is idempotent — deleting a missing key is a no-op.\n * - {@link copy} / {@link move} throw `StorageObjectNotFoundError` when the\n *   source is missing, and overwrite the destination if it already exists. Both\n *   operate within this backend only (same bucket / root) — cross-backend or\n *   cross-bucket transfers are out of scope.\n * - {@link getSignedUrl} throws `StorageOperationNotSupportedError` on backends\n *   that cannot sign URLs.\n */\n@Injectable()\nexport abstract class StorageProvider {\n  /** Write `body` to `key`, overwriting any existing object. */\n  abstract write(key: string, body: Readable | Buffer | string, options?: StorageWriteOptions): Promise<void>;\n  /** Open a readable stream for `key`, optionally for a byte range. Throws if the key does not exist. */\n  abstract read(key: string, options?: StorageReadOptions): Promise<Readable>;\n  /** Fetch metadata for `key` without reading its body. Throws if absent. */\n  abstract stat(key: string): Promise<StorageObjectMetadata>;\n  /** Resolve to `true` if `key` exists, `false` otherwise. Never throws for absence. */\n  abstract exists(key: string): Promise<boolean>;\n  /** Delete `key`. A no-op if the key does not exist. */\n  abstract delete(key: string): Promise<void>;\n  /** Copy `sourceKey` to `destinationKey` within this backend, overwriting the destination. Throws if the source is missing. */\n  abstract copy(sourceKey: string, destinationKey: string): Promise<void>;\n  /** Move/rename `sourceKey` to `destinationKey` within this backend, overwriting the destination. Throws if the source is missing. */\n  abstract move(sourceKey: string, destinationKey: string): Promise<void>;\n  /** List a single page of objects, optionally filtered by prefix. */\n  abstract list(options?: StorageListOptions): Promise<StorageListResult>;\n  /** Generate a time-limited signed URL for direct client read/write access. */\n  abstract getSignedUrl(key: string, options: SignedUrlOptions): Promise<string>;\n}\n","import { ServerkitError } from '@maroonedsoftware/errors';\n\n/**\n * Base class for all errors thrown by a {@link StorageProvider}.\n *\n * Catch this to handle any storage failure generically; catch a subclass to\n * distinguish specific conditions (missing object, unsupported operation).\n * Extends `ServerkitError`, so `errorMiddleware` renders it as a 500 with any\n * attached `details`.\n */\nexport class StorageError extends ServerkitError {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options);\n    this.name = 'StorageError';\n  }\n}\n\n/**\n * Thrown when {@link StorageProvider.read} or {@link StorageProvider.stat} is\n * called for a key that does not exist. The offending key is available on\n * `key` for callers that want to surface it.\n */\nexport class StorageObjectNotFoundError extends StorageError {\n  constructor(\n    readonly key: string,\n    options?: { cause?: unknown },\n  ) {\n    super(`storage object '${key}' not found`, options);\n    this.name = 'StorageObjectNotFoundError';\n  }\n}\n\n/**\n * Thrown when the backend rejects an operation for permission reasons (an S3 or\n * GCS `403`, a local-filesystem `EACCES`/`EPERM`). The offending key is\n * available on `key`.\n */\nexport class StorageAccessDeniedError extends StorageError {\n  constructor(\n    readonly key: string,\n    options?: { cause?: unknown },\n  ) {\n    super(`access denied for storage object '${key}'`, options);\n    this.name = 'StorageAccessDeniedError';\n  }\n}\n\n/**\n * Thrown when an operation is not supported by the active backend — for\n * example {@link StorageProvider.getSignedUrl} on a disk provider that has no\n * public base URL configured.\n */\nexport class StorageOperationNotSupportedError extends StorageError {\n  constructor(operation: string, options?: { cause?: unknown }) {\n    super(`storage operation '${operation}' is not supported by this backend`, options);\n    this.name = 'StorageOperationNotSupportedError';\n  }\n}\n","import { Injectable } from 'injectkit';\nimport { createReadStream, createWriteStream } from 'node:fs';\nimport { copyFile, mkdir, readdir, rename, rm, stat as fsStat, unlink } from 'node:fs/promises';\nimport { dirname, join, posix, relative, resolve, sep } from 'node:path';\nimport { pipeline } from 'node:stream/promises';\nimport { Readable } from 'node:stream';\nimport { DateTime } from 'luxon';\nimport mime from 'mime-types';\nimport { StorageAccessDeniedError, StorageObjectNotFoundError, StorageOperationNotSupportedError } from './storage.errors.js';\nimport type {\n  SignedUrlOptions,\n  StorageListOptions,\n  StorageListResult,\n  StorageObjectMetadata,\n  StorageReadOptions,\n  StorageWriteOptions,\n} from './storage.provider.js';\nimport { StorageProvider } from './storage.provider.js';\n\n/**\n * Construction options for {@link DiskStorageProvider}.\n *\n * A class (not an interface) so it can serve as an InjectKit token — register\n * an instance and the container can construct {@link DiskStorageProvider}.\n */\nexport class DiskStorageProviderOptions {\n  /** Root directory the provider stores objects under. */\n  readonly rootDir: string;\n  /**\n   * Base URL objects are publicly served from. When set, {@link DiskStorageProvider.getSignedUrl}\n   * returns `${publicBaseUrl}/${key}`; when omitted, signing is unsupported.\n   */\n  readonly publicBaseUrl?: string;\n\n  constructor(init: { rootDir: string; publicBaseUrl?: string }) {\n    this.rootDir = init.rootDir;\n    this.publicBaseUrl = init.publicBaseUrl;\n  }\n}\n\n/**\n * {@link StorageProvider} backed by the local filesystem rooted at a directory.\n *\n * Keys map to paths under the root; nested keys create intermediate directories\n * on write. User metadata is not persisted (the filesystem has no native slot),\n * and `getSignedUrl` requires a configured `publicBaseUrl`. Useful for local\n * development and as an in-process test double.\n */\n@Injectable()\nexport class DiskStorageProvider extends StorageProvider {\n  constructor(private readonly options: DiskStorageProviderOptions) {\n    super();\n  }\n\n  async write(key: string, body: Readable | Buffer | string, _options?: StorageWriteOptions): Promise<void> {\n    const path = this.resolveKey(key);\n    await mkdir(dirname(path), { recursive: true });\n    const source = body instanceof Readable ? body : Readable.from(body instanceof Buffer ? body : Buffer.from(body));\n    await pipeline(source, createWriteStream(path));\n  }\n\n  async read(key: string, options?: StorageReadOptions): Promise<Readable> {\n    const path = this.resolveKey(key);\n    await this.assertExists(key, path);\n    // `start`/`end` map directly to fs's inclusive byte offsets.\n    return options?.range ? createReadStream(path, { start: options.range.start, end: options.range.end }) : createReadStream(path);\n  }\n\n  async stat(key: string): Promise<StorageObjectMetadata> {\n    const path = this.resolveKey(key);\n    const stats = await this.assertExists(key, path);\n    const contentType = mime.lookup(path);\n    return {\n      key,\n      size: stats.size,\n      contentType: contentType === false ? undefined : contentType,\n      lastModified: DateTime.fromJSDate(stats.mtime),\n    };\n  }\n\n  async exists(key: string): Promise<boolean> {\n    try {\n      const stats = await fsStat(this.resolveKey(key));\n      return stats.isFile();\n    } catch (error) {\n      if (isNotFound(error)) {\n        return false;\n      }\n      if (isAccessDenied(error)) {\n        throw new StorageAccessDeniedError(key, { cause: error });\n      }\n      throw error;\n    }\n  }\n\n  async delete(key: string): Promise<void> {\n    // `force: true` makes this idempotent — no error when the path is absent.\n    await rm(this.resolveKey(key), { force: true });\n  }\n\n  async copy(sourceKey: string, destinationKey: string): Promise<void> {\n    const source = this.resolveKey(sourceKey);\n    const destination = this.resolveKey(destinationKey);\n    await this.assertExists(sourceKey, source);\n    await mkdir(dirname(destination), { recursive: true });\n    await copyFile(source, destination);\n  }\n\n  async move(sourceKey: string, destinationKey: string): Promise<void> {\n    const source = this.resolveKey(sourceKey);\n    const destination = this.resolveKey(destinationKey);\n    await this.assertExists(sourceKey, source);\n    await mkdir(dirname(destination), { recursive: true });\n    try {\n      // Atomic and cheap on the same filesystem.\n      await rename(source, destination);\n    } catch (error) {\n      // `rename` cannot cross filesystem boundaries — fall back to copy + delete.\n      if (typeof error === 'object' && error !== null && (error as NodeJS.ErrnoException).code === 'EXDEV') {\n        await copyFile(source, destination);\n        await unlink(source);\n        return;\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * Lists objects under the root, optionally filtered by prefix.\n   *\n   * Note: this walks the entire directory tree and `stat`s every matching file\n   * on each call — pagination slices an in-memory list, it does not make paging\n   * cheaper. Fine for development and modest trees (its intended use); avoid\n   * pointing it at very large directories.\n   */\n  async list(options?: StorageListOptions): Promise<StorageListResult> {\n    const prefix = options?.prefix ?? '';\n    const keys: string[] = [];\n    await this.walk(this.options.rootDir, keys);\n    const matched = keys.filter(key => key.startsWith(prefix)).sort();\n\n    // Cursor is the last key returned by the previous page; resume after it.\n    const start = options?.cursor ? matched.findIndex(key => key > options.cursor!) : 0;\n    const from = start === -1 ? matched.length : start;\n    const limit = options?.limit ?? matched.length;\n    const page = matched.slice(from, from + limit);\n\n    const objects = await Promise.all(page.map(key => this.stat(key)));\n    const hasMore = from + limit < matched.length;\n    return {\n      objects,\n      cursor: hasMore && page.length > 0 ? page[page.length - 1] : undefined,\n    };\n  }\n\n  async getSignedUrl(key: string, _options: SignedUrlOptions): Promise<string> {\n    if (!this.options.publicBaseUrl) {\n      throw new StorageOperationNotSupportedError('getSignedUrl');\n    }\n    // Normalise the key against the root for traversal safety, then join to the base URL.\n    this.resolveKey(key);\n    // Encode each path segment so keys with spaces or reserved characters yield a valid URL.\n    const encodedPath = key\n      .replace(/^\\/+/, '')\n      .split('/')\n      .map(encodeURIComponent)\n      .join('/');\n    return `${this.options.publicBaseUrl.replace(/\\/+$/, '')}/${encodedPath}`;\n  }\n\n  /** Resolve a key to an absolute path, rejecting traversal that escapes the root. */\n  private resolveKey(key: string): string {\n    const path = resolve(this.options.rootDir, key);\n    const rel = relative(this.options.rootDir, path);\n    if (rel === '' || rel.startsWith('..') || rel.startsWith(`..${sep}`)) {\n      throw new StorageOperationNotSupportedError(`key '${key}' resolves outside the storage root`);\n    }\n    return path;\n  }\n\n  private async assertExists(key: string, path: string) {\n    try {\n      const stats = await fsStat(path);\n      if (!stats.isFile()) {\n        throw new StorageObjectNotFoundError(key);\n      }\n      return stats;\n    } catch (error) {\n      if (isNotFound(error)) {\n        throw new StorageObjectNotFoundError(key, { cause: error });\n      }\n      if (isAccessDenied(error)) {\n        throw new StorageAccessDeniedError(key, { cause: error });\n      }\n      throw error;\n    }\n  }\n\n  /** Recursively collect file keys (root-relative, `/`-separated) under `dir`. */\n  private async walk(dir: string, into: string[]): Promise<void> {\n    const entries = await readdir(dir, { withFileTypes: true });\n    for (const entry of entries) {\n      const full = join(dir, entry.name);\n      if (entry.isDirectory()) {\n        await this.walk(full, into);\n      } else if (entry.isFile()) {\n        into.push(relative(this.options.rootDir, full).split(sep).join(posix.sep));\n      }\n    }\n  }\n}\n\nfunction isNotFound(error: unknown): boolean {\n  return typeof error === 'object' && error !== null && (error as NodeJS.ErrnoException).code === 'ENOENT';\n}\n\nfunction isAccessDenied(error: unknown): boolean {\n  if (typeof error !== 'object' || error === null) {\n    return false;\n  }\n  const code = (error as NodeJS.ErrnoException).code;\n  return code === 'EACCES' || code === 'EPERM';\n}\n","import { Injectable } from 'injectkit';\nimport { Readable } from 'node:stream';\nimport { DateTime } from 'luxon';\nimport {\n  CopyObjectCommand,\n  DeleteObjectCommand,\n  GetObjectCommand,\n  HeadObjectCommand,\n  ListObjectsV2Command,\n  PutObjectCommand,\n  type S3Client,\n} from '@aws-sdk/client-s3';\nimport { Upload } from '@aws-sdk/lib-storage';\nimport { getSignedUrl } from '@aws-sdk/s3-request-presigner';\nimport { StorageAccessDeniedError, StorageObjectNotFoundError } from './storage.errors.js';\nimport type {\n  SignedUrlOptions,\n  StorageListOptions,\n  StorageListResult,\n  StorageObjectMetadata,\n  StorageReadOptions,\n  StorageWriteOptions,\n} from './storage.provider.js';\nimport { StorageProvider } from './storage.provider.js';\n\n/**\n * Construction options for {@link S3StorageProvider}.\n *\n * A class (not an interface) so it can serve as an InjectKit token — register\n * an instance and the container can construct {@link S3StorageProvider}.\n */\nexport class S3StorageProviderOptions {\n  /** Name of the bucket all keys live in. */\n  readonly bucket: string;\n\n  constructor(init: { bucket: string }) {\n    this.bucket = init.bucket;\n  }\n}\n\n/**\n * {@link StorageProvider} backed by an AWS S3 (or S3-compatible) bucket.\n *\n * Streaming writes go through `@aws-sdk/lib-storage`'s multipart `Upload`;\n * buffer/string writes use a single `PutObject`. Signed URLs are produced with\n * `@aws-sdk/s3-request-presigner`.\n */\n@Injectable()\nexport class S3StorageProvider extends StorageProvider {\n  constructor(\n    private readonly client: S3Client,\n    private readonly options: S3StorageProviderOptions,\n  ) {\n    super();\n  }\n\n  async write(key: string, body: Readable | Buffer | string, options?: StorageWriteOptions): Promise<void> {\n    const shared = {\n      Bucket: this.options.bucket,\n      Key: key,\n      ContentType: options?.contentType,\n      ContentLength: options?.contentLength,\n      CacheControl: options?.cacheControl,\n      Metadata: options?.metadata,\n    };\n\n    if (body instanceof Readable) {\n      // lib-storage streams the body, automatically switching to multipart for large objects.\n      const upload = new Upload({ client: this.client, params: { ...shared, Body: body } });\n      await upload.done();\n      return;\n    }\n\n    await this.client.send(new PutObjectCommand({ ...shared, Body: body }));\n  }\n\n  async read(key: string, options?: StorageReadOptions): Promise<Readable> {\n    try {\n      const response = await this.client.send(\n        new GetObjectCommand({ Bucket: this.options.bucket, Key: key, Range: toRangeHeader(options?.range) }),\n      );\n      return response.Body as Readable;\n    } catch (error) {\n      throw this.mapError(key, error);\n    }\n  }\n\n  async stat(key: string): Promise<StorageObjectMetadata> {\n    try {\n      const head = await this.client.send(new HeadObjectCommand({ Bucket: this.options.bucket, Key: key }));\n      return {\n        key,\n        size: head.ContentLength ?? 0,\n        contentType: head.ContentType,\n        etag: head.ETag,\n        lastModified: head.LastModified ? DateTime.fromJSDate(head.LastModified) : undefined,\n        metadata: head.Metadata,\n      };\n    } catch (error) {\n      throw this.mapError(key, error);\n    }\n  }\n\n  async exists(key: string): Promise<boolean> {\n    try {\n      await this.client.send(new HeadObjectCommand({ Bucket: this.options.bucket, Key: key }));\n      return true;\n    } catch (error) {\n      if (isNotFound(error)) {\n        return false;\n      }\n      // A 403 is a permission failure, not absence — surface it.\n      throw this.mapError(key, error);\n    }\n  }\n\n  async delete(key: string): Promise<void> {\n    // S3 DeleteObject is idempotent — deleting a missing key succeeds.\n    await this.client.send(new DeleteObjectCommand({ Bucket: this.options.bucket, Key: key }));\n  }\n\n  /**\n   * Server-side copy via `CopyObjectCommand`.\n   *\n   * Note: S3's single-request `CopyObject` is capped at 5 GB. Copying a larger\n   * object requires a multipart copy (`UploadPartCopy`), which this provider\n   * does not yet implement — such copies will fail. {@link move} inherits the\n   * same limit since it delegates to `copy`.\n   */\n  async copy(sourceKey: string, destinationKey: string): Promise<void> {\n    try {\n      await this.client.send(\n        new CopyObjectCommand({\n          Bucket: this.options.bucket,\n          Key: destinationKey,\n          // CopySource must be the URL-encoded `bucket/key` of the source object.\n          CopySource: `${this.options.bucket}/${encodeURIComponent(sourceKey)}`,\n        }),\n      );\n    } catch (error) {\n      throw this.mapError(sourceKey, error);\n    }\n  }\n\n  async move(sourceKey: string, destinationKey: string): Promise<void> {\n    // S3 has no native move — copy then delete the source.\n    await this.copy(sourceKey, destinationKey);\n    await this.delete(sourceKey);\n  }\n\n  async list(options?: StorageListOptions): Promise<StorageListResult> {\n    const response = await this.client.send(\n      new ListObjectsV2Command({\n        Bucket: this.options.bucket,\n        Prefix: options?.prefix,\n        MaxKeys: options?.limit,\n        ContinuationToken: options?.cursor,\n      }),\n    );\n\n    const objects: StorageObjectMetadata[] = (response.Contents ?? []).map(item => ({\n      key: item.Key ?? '',\n      size: item.Size ?? 0,\n      etag: item.ETag,\n      lastModified: item.LastModified ? DateTime.fromJSDate(item.LastModified) : undefined,\n    }));\n\n    return {\n      objects,\n      cursor: response.IsTruncated ? response.NextContinuationToken : undefined,\n    };\n  }\n\n  async getSignedUrl(key: string, options: SignedUrlOptions): Promise<string> {\n    const command =\n      options.operation === 'write'\n        ? new PutObjectCommand({ Bucket: this.options.bucket, Key: key, ContentType: options.contentType })\n        : new GetObjectCommand({ Bucket: this.options.bucket, Key: key });\n    return getSignedUrl(this.client, command, { expiresIn: Math.round(options.expiresIn.as('seconds')) });\n  }\n\n  private mapError(key: string, error: unknown): unknown {\n    if (isNotFound(error)) {\n      return new StorageObjectNotFoundError(key, { cause: error });\n    }\n    if (isAccessDenied(error)) {\n      return new StorageAccessDeniedError(key, { cause: error });\n    }\n    return error;\n  }\n}\n\nfunction errorName(error: unknown): string | undefined {\n  return typeof error === 'object' && error !== null ? (error as { name?: string }).name : undefined;\n}\n\nfunction statusCode(error: unknown): number | undefined {\n  return typeof error === 'object' && error !== null ? (error as { $metadata?: { httpStatusCode?: number } }).$metadata?.httpStatusCode : undefined;\n}\n\nfunction isNotFound(error: unknown): boolean {\n  const name = errorName(error);\n  return name === 'NoSuchKey' || name === 'NotFound' || statusCode(error) === 404;\n}\n\nfunction isAccessDenied(error: unknown): boolean {\n  return errorName(error) === 'AccessDenied' || statusCode(error) === 403;\n}\n\n/** Build an HTTP `Range` header (`bytes=start-end`) from an inclusive byte range. */\nfunction toRangeHeader(range?: { start: number; end?: number }): string | undefined {\n  return range ? `bytes=${range.start}-${range.end ?? ''}` : undefined;\n}\n","import { Injectable } from 'injectkit';\nimport { Readable } from 'node:stream';\nimport { pipeline } from 'node:stream/promises';\nimport { DateTime } from 'luxon';\nimport type { File, Storage } from '@google-cloud/storage';\nimport { StorageAccessDeniedError, StorageObjectNotFoundError } from './storage.errors.js';\nimport type {\n  SignedUrlOptions,\n  StorageListOptions,\n  StorageListResult,\n  StorageObjectMetadata,\n  StorageReadOptions,\n  StorageWriteOptions,\n} from './storage.provider.js';\nimport { StorageProvider } from './storage.provider.js';\n\n/**\n * Construction options for {@link GcsStorageProvider}.\n *\n * A class (not an interface) so it can serve as an InjectKit token — register\n * an instance and the container can construct {@link GcsStorageProvider}.\n */\nexport class GcsStorageProviderOptions {\n  /** Name of the bucket all keys live in. */\n  readonly bucket: string;\n\n  constructor(init: { bucket: string }) {\n    this.bucket = init.bucket;\n  }\n}\n\n/**\n * {@link StorageProvider} backed by a Google Cloud Storage bucket.\n */\n@Injectable()\nexport class GcsStorageProvider extends StorageProvider {\n  constructor(\n    private readonly client: Storage,\n    private readonly options: GcsStorageProviderOptions,\n  ) {\n    super();\n  }\n\n  async write(key: string, body: Readable | Buffer | string, options?: StorageWriteOptions): Promise<void> {\n    const file = this.file(key);\n    const metadata = {\n      contentType: options?.contentType,\n      cacheControl: options?.cacheControl,\n      metadata: options?.metadata,\n    };\n\n    if (body instanceof Readable) {\n      await pipeline(body, file.createWriteStream({ metadata }));\n      return;\n    }\n\n    await file.save(body instanceof Buffer ? body : Buffer.from(body), { metadata });\n  }\n\n  async read(key: string, options?: StorageReadOptions): Promise<Readable> {\n    // GCS surfaces a missing object on the stream's 'error' event rather than as\n    // a rejected promise, so pre-check existence to honour the not-found contract.\n    const exists = await this.exists(key);\n    if (!exists) {\n      throw new StorageObjectNotFoundError(key);\n    }\n    // `start`/`end` are inclusive byte offsets, matching the read contract.\n    return this.file(key).createReadStream(options?.range ? { start: options.range.start, end: options.range.end } : undefined);\n  }\n\n  async stat(key: string): Promise<StorageObjectMetadata> {\n    try {\n      const [metadata] = await this.file(key).getMetadata();\n      return {\n        key,\n        size: typeof metadata.size === 'string' ? Number(metadata.size) : (metadata.size ?? 0),\n        contentType: metadata.contentType,\n        etag: metadata.etag,\n        lastModified: metadata.updated ? DateTime.fromISO(metadata.updated) : undefined,\n        metadata: metadata.metadata as Record<string, string> | undefined,\n      };\n    } catch (error) {\n      throw this.mapError(key, error);\n    }\n  }\n\n  async exists(key: string): Promise<boolean> {\n    try {\n      const [exists] = await this.file(key).exists();\n      return exists;\n    } catch (error) {\n      // `exists()` reports absence as `false`; a thrown error is a real failure\n      // (e.g. a permission denial) and should surface.\n      throw this.mapError(key, error);\n    }\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.file(key).delete({ ignoreNotFound: true });\n  }\n\n  async copy(sourceKey: string, destinationKey: string): Promise<void> {\n    try {\n      await this.file(sourceKey).copy(this.file(destinationKey));\n    } catch (error) {\n      throw this.mapError(sourceKey, error);\n    }\n  }\n\n  async move(sourceKey: string, destinationKey: string): Promise<void> {\n    try {\n      // GCS `move` is a server-side copy followed by a delete of the source.\n      await this.file(sourceKey).move(this.file(destinationKey));\n    } catch (error) {\n      throw this.mapError(sourceKey, error);\n    }\n  }\n\n  async list(options?: StorageListOptions): Promise<StorageListResult> {\n    const [files, nextQuery] = await this.client.bucket(this.options.bucket).getFiles({\n      prefix: options?.prefix,\n      maxResults: options?.limit,\n      pageToken: options?.cursor,\n      autoPaginate: false,\n    });\n\n    const objects: StorageObjectMetadata[] = files.map(file => ({\n      key: file.name,\n      size: typeof file.metadata.size === 'string' ? Number(file.metadata.size) : (file.metadata.size ?? 0),\n      contentType: file.metadata.contentType,\n      etag: file.metadata.etag,\n      lastModified: file.metadata.updated ? DateTime.fromISO(file.metadata.updated) : undefined,\n    }));\n\n    return {\n      objects,\n      cursor: (nextQuery as { pageToken?: string } | undefined)?.pageToken,\n    };\n  }\n\n  async getSignedUrl(key: string, options: SignedUrlOptions): Promise<string> {\n    const [url] = await this.file(key).getSignedUrl({\n      version: 'v4',\n      action: options.operation === 'write' ? 'write' : 'read',\n      expires: DateTime.now().plus(options.expiresIn).toMillis(),\n      contentType: options.operation === 'write' ? options.contentType : undefined,\n    });\n    return url;\n  }\n\n  private file(key: string): File {\n    return this.client.bucket(this.options.bucket).file(key);\n  }\n\n  private mapError(key: string, error: unknown): unknown {\n    if (isNotFound(error)) {\n      return new StorageObjectNotFoundError(key, { cause: error });\n    }\n    if (isAccessDenied(error)) {\n      return new StorageAccessDeniedError(key, { cause: error });\n    }\n    return error;\n  }\n}\n\nfunction statusCode(error: unknown): number | undefined {\n  return typeof error === 'object' && error !== null ? (error as { code?: number }).code : undefined;\n}\n\nfunction isNotFound(error: unknown): boolean {\n  return statusCode(error) === 404;\n}\n\nfunction isAccessDenied(error: unknown): boolean {\n  return statusCode(error) === 403;\n}\n"],"mappings":"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","names":["Injectable","StorageProvider","ServerkitError","StorageError","ServerkitError","message","options","name","StorageObjectNotFoundError","key","StorageAccessDeniedError","StorageOperationNotSupportedError","operation","Injectable","createReadStream","createWriteStream","copyFile","mkdir","readdir","rename","rm","stat","fsStat","unlink","dirname","join","posix","relative","resolve","sep","pipeline","Readable","DateTime","mime","DiskStorageProviderOptions","rootDir","publicBaseUrl","init","DiskStorageProvider","StorageProvider","options","write","key","body","_options","path","resolveKey","mkdir","dirname","recursive","source","Readable","from","Buffer","pipeline","createWriteStream","read","assertExists","range","createReadStream","start","end","stat","stats","contentType","mime","lookup","size","undefined","lastModified","DateTime","fromJSDate","mtime","exists","fsStat","isFile","error","isNotFound","isAccessDenied","StorageAccessDeniedError","cause","delete","rm","force","copy","sourceKey","destinationKey","destination","copyFile","move","rename","code","unlink","list","prefix","keys","walk","matched","filter","startsWith","sort","cursor","findIndex","length","limit","page","slice","objects","Promise","all","map","hasMore","getSignedUrl","StorageOperationNotSupportedError","encodedPath","replace","split","encodeURIComponent","join","resolve","rel","relative","sep","StorageObjectNotFoundError","dir","into","entries","readdir","withFileTypes","entry","full","name","isDirectory","push","posix","Injectable","Readable","DateTime","CopyObjectCommand","DeleteObjectCommand","GetObjectCommand","HeadObjectCommand","ListObjectsV2Command","PutObjectCommand","Upload","getSignedUrl","S3StorageProviderOptions","bucket","init","S3StorageProvider","StorageProvider","client","options","write","key","body","shared","Bucket","Key","ContentType","contentType","ContentLength","contentLength","CacheControl","cacheControl","Metadata","metadata","Readable","upload","Upload","params","Body","done","send","PutObjectCommand","read","response","GetObjectCommand","Range","toRangeHeader","range","error","mapError","stat","head","HeadObjectCommand","size","etag","ETag","lastModified","LastModified","DateTime","fromJSDate","undefined","exists","isNotFound","delete","DeleteObjectCommand","copy","sourceKey","destinationKey","CopyObjectCommand","CopySource","encodeURIComponent","move","list","ListObjectsV2Command","Prefix","prefix","MaxKeys","limit","ContinuationToken","cursor","objects","Contents","map","item","Size","IsTruncated","NextContinuationToken","getSignedUrl","command","operation","expiresIn","Math","round","as","StorageObjectNotFoundError","cause","isAccessDenied","StorageAccessDeniedError","errorName","name","statusCode","$metadata","httpStatusCode","start","end","Injectable","Readable","pipeline","DateTime","GcsStorageProviderOptions","bucket","init","GcsStorageProvider","StorageProvider","client","options","write","key","body","file","metadata","contentType","cacheControl","Readable","pipeline","createWriteStream","save","Buffer","from","read","exists","StorageObjectNotFoundError","createReadStream","range","start","end","undefined","stat","getMetadata","size","Number","etag","lastModified","updated","DateTime","fromISO","error","mapError","delete","ignoreNotFound","copy","sourceKey","destinationKey","move","list","files","nextQuery","getFiles","prefix","maxResults","limit","pageToken","cursor","autoPaginate","objects","map","name","getSignedUrl","url","version","action","operation","expires","now","plus","expiresIn","toMillis","isNotFound","cause","isAccessDenied","StorageAccessDeniedError","statusCode","code"]}

package/dist/s3.storage.provider.d.ts

@@ -0,0 +1,48 @@
+import { Readable } from 'node:stream';
+import { type S3Client } from '@aws-sdk/client-s3';
+import type { SignedUrlOptions, StorageListOptions, StorageListResult, StorageObjectMetadata, StorageReadOptions, StorageWriteOptions } from './storage.provider.js';
+import { StorageProvider } from './storage.provider.js';
+/**
+ * Construction options for {@link S3StorageProvider}.
+ *
+ * A class (not an interface) so it can serve as an InjectKit token — register
+ * an instance and the container can construct {@link S3StorageProvider}.
+ */
+export declare class S3StorageProviderOptions {
+    /** Name of the bucket all keys live in. */
+    readonly bucket: string;
+    constructor(init: {
+        bucket: string;
+    });
+}
+/**
+ * {@link StorageProvider} backed by an AWS S3 (or S3-compatible) bucket.
+ *
+ * Streaming writes go through `@aws-sdk/lib-storage`'s multipart `Upload`;
+ * buffer/string writes use a single `PutObject`. Signed URLs are produced with
+ * `@aws-sdk/s3-request-presigner`.
+ */
+export declare class S3StorageProvider extends StorageProvider {
+    private readonly client;
+    private readonly options;
+    constructor(client: S3Client, options: S3StorageProviderOptions);
+    write(key: string, body: Readable | Buffer | string, options?: StorageWriteOptions): Promise<void>;
+    read(key: string, options?: StorageReadOptions): Promise<Readable>;
+    stat(key: string): Promise<StorageObjectMetadata>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    /**
+     * Server-side copy via `CopyObjectCommand`.
+     *
+     * Note: S3's single-request `CopyObject` is capped at 5 GB. Copying a larger
+     * object requires a multipart copy (`UploadPartCopy`), which this provider
+     * does not yet implement — such copies will fail. {@link move} inherits the
+     * same limit since it delegates to `copy`.
+     */
+    copy(sourceKey: string, destinationKey: string): Promise<void>;
+    move(sourceKey: string, destinationKey: string): Promise<void>;
+    list(options?: StorageListOptions): Promise<StorageListResult>;
+    getSignedUrl(key: string, options: SignedUrlOptions): Promise<string>;
+    private mapError;
+}
+//# sourceMappingURL=s3.storage.provider.d.ts.map

package/dist/s3.storage.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.storage.provider.d.ts","sourceRoot":"","sources":["../src/s3.storage.provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EAOL,KAAK,QAAQ,EACd,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;GAKG;AACH,qBAAa,wBAAwB;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE;CAGrC;AAED;;;;;;GAMG;AACH,qBACa,iBAAkB,SAAQ,eAAe;IAElD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,MAAM,EAAE,QAAQ,EAChB,OAAO,EAAE,wBAAwB;IAK9C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBlG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAWlE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAgBjD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAarC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxC;;;;;;;OAOG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe9D,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9D,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAuB9D,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ3E,OAAO,CAAC,QAAQ;CASjB"}

package/dist/storage.errors.d.ts

@@ -0,0 +1,47 @@
+import { ServerkitError } from '@maroonedsoftware/errors';
+/**
+ * Base class for all errors thrown by a {@link StorageProvider}.
+ *
+ * Catch this to handle any storage failure generically; catch a subclass to
+ * distinguish specific conditions (missing object, unsupported operation).
+ * Extends `ServerkitError`, so `errorMiddleware` renders it as a 500 with any
+ * attached `details`.
+ */
+export declare class StorageError extends ServerkitError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when {@link StorageProvider.read} or {@link StorageProvider.stat} is
+ * called for a key that does not exist. The offending key is available on
+ * `key` for callers that want to surface it.
+ */
+export declare class StorageObjectNotFoundError extends StorageError {
+    readonly key: string;
+    constructor(key: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when the backend rejects an operation for permission reasons (an S3 or
+ * GCS `403`, a local-filesystem `EACCES`/`EPERM`). The offending key is
+ * available on `key`.
+ */
+export declare class StorageAccessDeniedError extends StorageError {
+    readonly key: string;
+    constructor(key: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when an operation is not supported by the active backend — for
+ * example {@link StorageProvider.getSignedUrl} on a disk provider that has no
+ * public base URL configured.
+ */
+export declare class StorageOperationNotSupportedError extends StorageError {
+    constructor(operation: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=storage.errors.d.ts.map

package/dist/storage.errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.errors.d.ts","sourceRoot":"","sources":["../src/storage.errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;;;;;GAOG;AACH,qBAAa,YAAa,SAAQ,cAAc;gBAClC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,YAAY;IAExD,QAAQ,CAAC,GAAG,EAAE,MAAM;gBAAX,GAAG,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKhC;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,SAAQ,YAAY;IAEtD,QAAQ,CAAC,GAAG,EAAE,MAAM;gBAAX,GAAG,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKhC;AAED;;;;GAIG;AACH,qBAAa,iCAAkC,SAAQ,YAAY;gBACrD,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI7D"}

package/dist/storage.provider.d.ts

@@ -0,0 +1,126 @@
+import { Readable } from 'node:stream';
+import { DateTime, Duration } from 'luxon';
+/**
+ * Options applied when writing an object. All fields are optional; backends
+ * that cannot honour a given field ignore it (documented per provider).
+ */
+export interface StorageWriteOptions {
+    /** MIME type stored alongside the object (e.g. `image/png`). */
+    contentType?: string;
+    /** Byte length of the body, when known ahead of time. */
+    contentLength?: number;
+    /** `Cache-Control` header persisted with the object (cloud backends). */
+    cacheControl?: string;
+    /** Arbitrary user metadata. Unsupported on the disk backend (ignored). */
+    metadata?: Record<string, string>;
+}
+/**
+ * Options for {@link StorageProvider.read}.
+ */
+export interface StorageReadOptions {
+    /**
+     * Restrict the read to a byte range. `start` and `end` are both inclusive
+     * (HTTP `Range` semantics); omit `end` to read from `start` to the end of the
+     * object. Useful for media streaming and resumable downloads.
+     */
+    range?: {
+        start: number;
+        end?: number;
+    };
+}
+/**
+ * Metadata describing a stored object, returned by {@link StorageProvider.stat}
+ * and {@link StorageProvider.list}.
+ */
+export interface StorageObjectMetadata {
+    /** The object's key. */
+    key: string;
+    /** Size in bytes. */
+    size: number;
+    /** MIME type, when known. */
+    contentType?: string;
+    /** Backend entity tag, when provided. */
+    etag?: string;
+    /** Last modification time, when known. */
+    lastModified?: DateTime;
+    /** User metadata, when the backend supports and returns it. */
+    metadata?: Record<string, string>;
+}
+/**
+ * Options for {@link StorageProvider.list}.
+ */
+export interface StorageListOptions {
+    /** Restrict results to keys beginning with this prefix. */
+    prefix?: string;
+    /** Maximum number of objects to return in this page. */
+    limit?: number;
+    /** Opaque continuation token from a previous {@link StorageListResult}. */
+    cursor?: string;
+}
+/**
+ * A single page of {@link StorageProvider.list} results.
+ */
+export interface StorageListResult {
+    /** Objects in this page. */
+    objects: StorageObjectMetadata[];
+    /** Continuation token for the next page, or `undefined` when exhausted. */
+    cursor?: string;
+}
+/** Whether a signed URL grants read (download) or write (upload) access. */
+export type SignedUrlOperation = 'read' | 'write';
+/**
+ * Options for {@link StorageProvider.getSignedUrl}.
+ */
+export interface SignedUrlOptions {
+    /** The operation the URL authorises. */
+    operation: SignedUrlOperation;
+    /** How long the URL remains valid. */
+    expiresIn: Duration;
+    /** Content type the client must use when uploading (`write` URLs). */
+    contentType?: string;
+}
+/**
+ * Backend-agnostic object storage. Implementations wrap a concrete backend
+ * (local disk, AWS S3, Google Cloud Storage). Bind a concrete provider to this
+ * token in the DI container so consumers depend only on the abstraction:
+ *
+ * ```ts
+ * container.bind(StorageProvider).toConstantValue(new DiskStorageProvider({ rootDir: '/var/data' }));
+ * ```
+ *
+ * Keys are hierarchical, `/`-separated paths (e.g. `users/42/avatar.png`), not
+ * flat filenames.
+ *
+ * ## Behaviour contract
+ * - {@link read} / {@link stat} on a missing key throw `StorageObjectNotFoundError`.
+ * - {@link exists} never throws for a missing key — it returns `false`.
+ * - Operations that hit a permission failure throw `StorageAccessDeniedError`.
+ * - {@link delete} is idempotent — deleting a missing key is a no-op.
+ * - {@link copy} / {@link move} throw `StorageObjectNotFoundError` when the
+ *   source is missing, and overwrite the destination if it already exists. Both
+ *   operate within this backend only (same bucket / root) — cross-backend or
+ *   cross-bucket transfers are out of scope.
+ * - {@link getSignedUrl} throws `StorageOperationNotSupportedError` on backends
+ *   that cannot sign URLs.
+ */
+export declare abstract class StorageProvider {
+    /** Write `body` to `key`, overwriting any existing object. */
+    abstract write(key: string, body: Readable | Buffer | string, options?: StorageWriteOptions): Promise<void>;
+    /** Open a readable stream for `key`, optionally for a byte range. Throws if the key does not exist. */
+    abstract read(key: string, options?: StorageReadOptions): Promise<Readable>;
+    /** Fetch metadata for `key` without reading its body. Throws if absent. */
+    abstract stat(key: string): Promise<StorageObjectMetadata>;
+    /** Resolve to `true` if `key` exists, `false` otherwise. Never throws for absence. */
+    abstract exists(key: string): Promise<boolean>;
+    /** Delete `key`. A no-op if the key does not exist. */
+    abstract delete(key: string): Promise<void>;
+    /** Copy `sourceKey` to `destinationKey` within this backend, overwriting the destination. Throws if the source is missing. */
+    abstract copy(sourceKey: string, destinationKey: string): Promise<void>;
+    /** Move/rename `sourceKey` to `destinationKey` within this backend, overwriting the destination. Throws if the source is missing. */
+    abstract move(sourceKey: string, destinationKey: string): Promise<void>;
+    /** List a single page of objects, optionally filtered by prefix. */
+    abstract list(options?: StorageListOptions): Promise<StorageListResult>;
+    /** Generate a time-limited signed URL for direct client read/write access. */
+    abstract getSignedUrl(key: string, options: SignedUrlOptions): Promise<string>;
+}
+//# sourceMappingURL=storage.provider.d.ts.map

package/dist/storage.provider.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maroonedsoftware/storage",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Storage utilities for ServerKit.",
   "author": {
     "name": "Marooned Software",