@fonderie/storage 0.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,52 @@
+# @fonderie/storage
+
+Content-agnostic, provider-abstracted **object storage** — store any bytes
+behind one interface, on Postgres, disk, or any S3-compatible service
+(S3 / MinIO / R2 / B2 / Spaces). The low-dependency foundation other bricks
+build on: `@fonderie/media` (uploads/serving), DB archives, datasets, anything.
+
+Start on Postgres for free; flip one config line to real object storage when
+scale (or a paying customer) justifies it — no consumer code changes.
+
+## The interface
+
+```ts
+interface IStorageProvider {
+  put(input: { bytes: Uint8Array; contentType: string }): Promise<{ ref: string }>;
+  get(ref: string): Promise<{ kind: 'bytes'; bytes: Uint8Array } | { kind: 'redirect'; url: string } | null>;
+  delete(ref: string): Promise<void>;
+}
+```
+
+`get` returns **bytes** (you serve/write/parse them) or a **redirect URL** (the
+backend serves it, e.g. an S3 presigned URL) — so consumers never branch on
+which backend is wired.
+
+## Providers
+
+- **`DbBlobProvider`** — bytes in Postgres (`fonderie_storage_blobs`). Zero infra;
+  one process + one database; atomic `pg_dump` backups. The default.
+- **`LocalFsProvider`** — bytes on the server filesystem. Single-box, no DB bloat.
+- **`S3Provider`** — any S3-compatible store. `get` returns a presigned redirect
+  so the app never proxies bytes.
+
+```ts
+import { DbBlobProvider, LocalFsProvider } from '@fonderie/storage';
+import { S3Provider } from '@fonderie/storage/s3'; // opt-in; pulls the AWS SDK peers
+
+const dev  = new DbBlobProvider(store);
+const prod = new S3Provider({ bucket: 'assets', endpoint: 'http://minio:9000', accessKeyId, secretAccessKey });
+```
+
+`S3Provider` needs the optional peers `@aws-sdk/client-s3` and
+`@aws-sdk/s3-request-presigner`; they're only loaded when you import
+`@fonderie/storage/s3`, so DbBlob/LocalFs users stay dependency-free.
+
+## Migration
+
+`DbBlobProvider` needs its table — run the migration alongside your others:
+
+```ts
+import { getMigrationsPath } from '@fonderie/storage/migrations';
+await new InternalMigrationRunner(store, getMigrationsPath()).run();
+```

package/brain/outcomes.md

@@ -0,0 +1,20 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/storage — outcomes
+
+What this package does to a running app: tables its migrations create,
+rows it seeds, routes it registers. Generated from the migration SQL and
+route tables in source — trust this file instead of reading `dist/` or
+downloading tarballs.
+
+## Database tables (after all migrations)
+
+### `fonderie_storage_blobs`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+bytes                    BYTEA NOT NULL
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+```
+
+Raw SQL ships in `node_modules/@fonderie/storage/dist/migrations/sql/` — read it there if you must; never download tarballs.

package/brain/signatures.md

@@ -0,0 +1,43 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/storage — signatures
+
+## @fonderie/storage
+
+Subpath exports: `@fonderie/storage/s3`, `@fonderie/storage/migrations`
+
+```ts
+interface IStorageProvider {
+    readonly name: string;
+    put(input: {
+        bytes: Uint8Array;
+        contentType: string;
+    }): Promise<IStoredRef>;
+    get(ref: string): Promise<IFetched | null>;
+    delete(ref: string): Promise<void>;
+}
+
+type IFetched = {
+    kind: 'bytes';
+    bytes: Uint8Array;
+} | {
+    kind: 'redirect';
+    url: string;
+};
+
+interface IStoredRef {
+    ref: string;
+}
+
+new DbBlobProvider(store: IStoreAdapter): DbBlobProvider
+  .name: "db-blob"
+  .put({ bytes }: { bytes: Uint8Array<ArrayBufferLike>; contentType: string; }): Promise<IStoredRef>
+  .get(ref: string): Promise<IFetched | null>
+  .delete(ref: string): Promise<void>
+
+new LocalFsProvider(dir: string): LocalFsProvider
+  .name: "local-fs"
+  .put({ bytes }: { bytes: Uint8Array<ArrayBufferLike>; contentType: string; }): Promise<IStoredRef>
+  .get(ref: string): Promise<IFetched | null>
+  .delete(ref: string): Promise<void>
+```

package/dist/index.cjs

@@ -0,0 +1,99 @@
+"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, {
+  DbBlobProvider: () => DbBlobProvider,
+  LocalFsProvider: () => LocalFsProvider
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/providers/db-blob.ts
+var DbBlobProvider = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  name = "db-blob";
+  async put({ bytes }) {
+    const rows = await this.store.query(
+      "INSERT INTO fonderie_storage_blobs (bytes) VALUES ($1) RETURNING id",
+      [Buffer.from(bytes)]
+    );
+    return { ref: rows[0].id };
+  }
+  async get(ref) {
+    const rows = await this.store.query(
+      "SELECT bytes FROM fonderie_storage_blobs WHERE id = $1",
+      [ref]
+    );
+    const row = rows[0];
+    return row ? { kind: "bytes", bytes: row.bytes } : null;
+  }
+  async delete(ref) {
+    await this.store.query("DELETE FROM fonderie_storage_blobs WHERE id = $1", [ref]);
+  }
+};
+
+// src/providers/local-fs.ts
+var import_promises = require("fs/promises");
+var import_node_crypto = require("crypto");
+var import_node_path = require("path");
+var LocalFsProvider = class {
+  name = "local-fs";
+  dir;
+  ready = null;
+  constructor(dir) {
+    this.dir = (0, import_node_path.resolve)(dir);
+  }
+  ensureDir() {
+    if (!this.ready) this.ready = (0, import_promises.mkdir)(this.dir, { recursive: true }).then(() => void 0);
+    return this.ready;
+  }
+  // Reject any ref that isn't a bare id, so a ref can never escape `dir`
+  // (path traversal). Ids we mint are UUIDs.
+  pathFor(ref) {
+    if (!/^[A-Za-z0-9_-]+$/.test(ref)) throw new Error("invalid storage ref");
+    return (0, import_node_path.join)(this.dir, ref);
+  }
+  async put({ bytes }) {
+    await this.ensureDir();
+    const ref = (0, import_node_crypto.randomUUID)();
+    await (0, import_promises.writeFile)(this.pathFor(ref), bytes);
+    return { ref };
+  }
+  async get(ref) {
+    try {
+      const bytes = await (0, import_promises.readFile)(this.pathFor(ref));
+      return { kind: "bytes", bytes };
+    } catch {
+      return null;
+    }
+  }
+  async delete(ref) {
+    await (0, import_promises.rm)(this.pathFor(ref), { force: true });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DbBlobProvider,
+  LocalFsProvider
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/providers/db-blob.ts","../src/providers/local-fs.ts"],"sourcesContent":["// @fonderie/storage — content-agnostic, provider-abstracted object storage.\n// The low-dependency foundation other bricks build on (media uploads, DB\n// archives). Store any bytes; swap DbBlob → S3/MinIO with one config line.\n//\n// S3Provider is intentionally NOT exported here — import it from\n// '@fonderie/storage/s3' so the AWS SDK is pulled in only when you use it.\nexport type { IStorageProvider, IFetched, IStoredRef } from './providers/types';\nexport { DbBlobProvider } from './providers/db-blob';\nexport { LocalFsProvider } from './providers/local-fs';\n","import type { IStoreAdapter } from '@fonderie/store';\n\nimport type { IFetched, IStorageProvider, IStoredRef } from './types';\n\n/**\n * Zero-infra provider: bytes live in Postgres (`fonderie_storage_blobs`, created\n * by this package's migration). Great for getting started and self-hosting — the\n * whole app is one Node process + one database, and a `pg_dump` captures the\n * objects atomically with the rows that reference them. Swap to `S3Provider`\n * when bandwidth or table size make object storage worth the extra moving part;\n * no consumer code changes, only the provider passed in config.\n */\nexport class DbBlobProvider implements IStorageProvider {\n\treadonly name = 'db-blob';\n\n\tconstructor(private readonly store: IStoreAdapter) {}\n\n\tasync put({ bytes }: { bytes: Uint8Array; contentType: string }): Promise<IStoredRef> {\n\t\tconst rows = await this.store.query<{ id: string }>(\n\t\t\t'INSERT INTO fonderie_storage_blobs (bytes) VALUES ($1) RETURNING id',\n\t\t\t[Buffer.from(bytes)],\n\t\t);\n\t\treturn { ref: rows[0]!.id };\n\t}\n\n\tasync get(ref: string): Promise<IFetched | null> {\n\t\tconst rows = await this.store.query<{ bytes: Buffer }>(\n\t\t\t'SELECT bytes FROM fonderie_storage_blobs WHERE id = $1',\n\t\t\t[ref],\n\t\t);\n\t\tconst row = rows[0];\n\t\treturn row ? { kind: 'bytes', bytes: row.bytes } : null;\n\t}\n\n\tasync delete(ref: string): Promise<void> {\n\t\tawait this.store.query('DELETE FROM fonderie_storage_blobs WHERE id = $1', [ref]);\n\t}\n}\n","import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';\nimport { randomUUID } from 'node:crypto';\nimport { join, resolve } from 'node:path';\n\nimport type { IFetched, IStorageProvider, IStoredRef } from './types';\n\n/**\n * Zero-infra provider: bytes live on the server's filesystem under `dir`. Useful\n * for a single-box deployment that wants objects off the database without\n * standing up object storage. The `ref` is an opaque filename; content type is\n * the consumer's concern, so nothing about the bytes-on-disk needs to encode it.\n *\n * Serves inline through the app like `DbBlobProvider` (no CDN in front), so at\n * real scale prefer `S3Provider` — same interface, one config line.\n */\nexport class LocalFsProvider implements IStorageProvider {\n\treadonly name = 'local-fs';\n\tprivate readonly dir: string;\n\tprivate ready: Promise<void> | null = null;\n\n\tconstructor(dir: string) {\n\t\tthis.dir = resolve(dir);\n\t}\n\n\tprivate ensureDir(): Promise<void> {\n\t\tif (!this.ready) this.ready = mkdir(this.dir, { recursive: true }).then(() => undefined);\n\t\treturn this.ready;\n\t}\n\n\t// Reject any ref that isn't a bare id, so a ref can never escape `dir`\n\t// (path traversal). Ids we mint are UUIDs.\n\tprivate pathFor(ref: string): string {\n\t\tif (!/^[A-Za-z0-9_-]+$/.test(ref)) throw new Error('invalid storage ref');\n\t\treturn join(this.dir, ref);\n\t}\n\n\tasync put({ bytes }: { bytes: Uint8Array; contentType: string }): Promise<IStoredRef> {\n\t\tawait this.ensureDir();\n\t\tconst ref = randomUUID();\n\t\tawait writeFile(this.pathFor(ref), bytes);\n\t\treturn { ref };\n\t}\n\n\tasync get(ref: string): Promise<IFetched | null> {\n\t\ttry {\n\t\t\tconst bytes = await readFile(this.pathFor(ref));\n\t\t\treturn { kind: 'bytes', bytes };\n\t\t} catch {\n\t\t\treturn null; // ENOENT (or an invalid ref) → treated as not found\n\t\t}\n\t}\n\n\tasync delete(ref: string): Promise<void> {\n\t\tawait rm(this.pathFor(ref), { force: true }); // force → no throw when already gone\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACYO,IAAM,iBAAN,MAAiD;AAAA,EAGvD,YAA6B,OAAsB;AAAtB;AAAA,EAAuB;AAAA,EAAvB;AAAA,EAFpB,OAAO;AAAA,EAIhB,MAAM,IAAI,EAAE,MAAM,GAAoE;AACrF,UAAM,OAAO,MAAM,KAAK,MAAM;AAAA,MAC7B;AAAA,MACA,CAAC,OAAO,KAAK,KAAK,CAAC;AAAA,IACpB;AACA,WAAO,EAAE,KAAK,KAAK,CAAC,EAAG,GAAG;AAAA,EAC3B;AAAA,EAEA,MAAM,IAAI,KAAuC;AAChD,UAAM,OAAO,MAAM,KAAK,MAAM;AAAA,MAC7B;AAAA,MACA,CAAC,GAAG;AAAA,IACL;AACA,UAAM,MAAM,KAAK,CAAC;AAClB,WAAO,MAAM,EAAE,MAAM,SAAS,OAAO,IAAI,MAAM,IAAI;AAAA,EACpD;AAAA,EAEA,MAAM,OAAO,KAA4B;AACxC,UAAM,KAAK,MAAM,MAAM,oDAAoD,CAAC,GAAG,CAAC;AAAA,EACjF;AACD;;;ACrCA,sBAA+C;AAC/C,yBAA2B;AAC3B,uBAA8B;AAavB,IAAM,kBAAN,MAAkD;AAAA,EAC/C,OAAO;AAAA,EACC;AAAA,EACT,QAA8B;AAAA,EAEtC,YAAY,KAAa;AACxB,SAAK,UAAM,0BAAQ,GAAG;AAAA,EACvB;AAAA,EAEQ,YAA2B;AAClC,QAAI,CAAC,KAAK,MAAO,MAAK,YAAQ,uBAAM,KAAK,KAAK,EAAE,WAAW,KAAK,CAAC,EAAE,KAAK,MAAM,MAAS;AACvF,WAAO,KAAK;AAAA,EACb;AAAA;AAAA;AAAA,EAIQ,QAAQ,KAAqB;AACpC,QAAI,CAAC,mBAAmB,KAAK,GAAG,EAAG,OAAM,IAAI,MAAM,qBAAqB;AACxE,eAAO,uBAAK,KAAK,KAAK,GAAG;AAAA,EAC1B;AAAA,EAEA,MAAM,IAAI,EAAE,MAAM,GAAoE;AACrF,UAAM,KAAK,UAAU;AACrB,UAAM,UAAM,+BAAW;AACvB,cAAM,2BAAU,KAAK,QAAQ,GAAG,GAAG,KAAK;AACxC,WAAO,EAAE,IAAI;AAAA,EACd;AAAA,EAEA,MAAM,IAAI,KAAuC;AAChD,QAAI;AACH,YAAM,QAAQ,UAAM,0BAAS,KAAK,QAAQ,GAAG,CAAC;AAC9C,aAAO,EAAE,MAAM,SAAS,MAAM;AAAA,IAC/B,QAAQ;AACP,aAAO;AAAA,IACR;AAAA,EACD;AAAA,EAEA,MAAM,OAAO,KAA4B;AACxC,cAAM,oBAAG,KAAK,QAAQ,GAAG,GAAG,EAAE,OAAO,KAAK,CAAC;AAAA,EAC5C;AACD;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,48 @@
+import { I as IStorageProvider, a as IStoredRef, b as IFetched } from './types-Cb480R4u.cjs';
+import { IStoreAdapter } from '@fonderie/store';
+
+/**
+ * Zero-infra provider: bytes live in Postgres (`fonderie_storage_blobs`, created
+ * by this package's migration). Great for getting started and self-hosting — the
+ * whole app is one Node process + one database, and a `pg_dump` captures the
+ * objects atomically with the rows that reference them. Swap to `S3Provider`
+ * when bandwidth or table size make object storage worth the extra moving part;
+ * no consumer code changes, only the provider passed in config.
+ */
+declare class DbBlobProvider implements IStorageProvider {
+    private readonly store;
+    readonly name = "db-blob";
+    constructor(store: IStoreAdapter);
+    put({ bytes }: {
+        bytes: Uint8Array;
+        contentType: string;
+    }): Promise<IStoredRef>;
+    get(ref: string): Promise<IFetched | null>;
+    delete(ref: string): Promise<void>;
+}
+
+/**
+ * Zero-infra provider: bytes live on the server's filesystem under `dir`. Useful
+ * for a single-box deployment that wants objects off the database without
+ * standing up object storage. The `ref` is an opaque filename; content type is
+ * the consumer's concern, so nothing about the bytes-on-disk needs to encode it.
+ *
+ * Serves inline through the app like `DbBlobProvider` (no CDN in front), so at
+ * real scale prefer `S3Provider` — same interface, one config line.
+ */
+declare class LocalFsProvider implements IStorageProvider {
+    readonly name = "local-fs";
+    private readonly dir;
+    private ready;
+    constructor(dir: string);
+    private ensureDir;
+    private pathFor;
+    put({ bytes }: {
+        bytes: Uint8Array;
+        contentType: string;
+    }): Promise<IStoredRef>;
+    get(ref: string): Promise<IFetched | null>;
+    delete(ref: string): Promise<void>;
+}
+
+export { DbBlobProvider, IFetched, IStorageProvider, IStoredRef, LocalFsProvider };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { I as IStorageProvider, a as IStoredRef, b as IFetched } from './types-Cb480R4u.js';
+import { IStoreAdapter } from '@fonderie/store';
+
+/**
+ * Zero-infra provider: bytes live in Postgres (`fonderie_storage_blobs`, created
+ * by this package's migration). Great for getting started and self-hosting — the
+ * whole app is one Node process + one database, and a `pg_dump` captures the
+ * objects atomically with the rows that reference them. Swap to `S3Provider`
+ * when bandwidth or table size make object storage worth the extra moving part;
+ * no consumer code changes, only the provider passed in config.
+ */
+declare class DbBlobProvider implements IStorageProvider {
+    private readonly store;
+    readonly name = "db-blob";
+    constructor(store: IStoreAdapter);
+    put({ bytes }: {
+        bytes: Uint8Array;
+        contentType: string;
+    }): Promise<IStoredRef>;
+    get(ref: string): Promise<IFetched | null>;
+    delete(ref: string): Promise<void>;
+}
+
+/**
+ * Zero-infra provider: bytes live on the server's filesystem under `dir`. Useful
+ * for a single-box deployment that wants objects off the database without
+ * standing up object storage. The `ref` is an opaque filename; content type is
+ * the consumer's concern, so nothing about the bytes-on-disk needs to encode it.
+ *
+ * Serves inline through the app like `DbBlobProvider` (no CDN in front), so at
+ * real scale prefer `S3Provider` — same interface, one config line.
+ */
+declare class LocalFsProvider implements IStorageProvider {
+    readonly name = "local-fs";
+    private readonly dir;
+    private ready;
+    constructor(dir: string);
+    private ensureDir;
+    private pathFor;
+    put({ bytes }: {
+        bytes: Uint8Array;
+        contentType: string;
+    }): Promise<IStoredRef>;
+    get(ref: string): Promise<IFetched | null>;
+    delete(ref: string): Promise<void>;
+}
+
+export { DbBlobProvider, IFetched, IStorageProvider, IStoredRef, LocalFsProvider };

package/dist/index.js

@@ -0,0 +1,71 @@
+// src/providers/db-blob.ts
+var DbBlobProvider = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  name = "db-blob";
+  async put({ bytes }) {
+    const rows = await this.store.query(
+      "INSERT INTO fonderie_storage_blobs (bytes) VALUES ($1) RETURNING id",
+      [Buffer.from(bytes)]
+    );
+    return { ref: rows[0].id };
+  }
+  async get(ref) {
+    const rows = await this.store.query(
+      "SELECT bytes FROM fonderie_storage_blobs WHERE id = $1",
+      [ref]
+    );
+    const row = rows[0];
+    return row ? { kind: "bytes", bytes: row.bytes } : null;
+  }
+  async delete(ref) {
+    await this.store.query("DELETE FROM fonderie_storage_blobs WHERE id = $1", [ref]);
+  }
+};
+
+// src/providers/local-fs.ts
+import { mkdir, readFile, rm, writeFile } from "fs/promises";
+import { randomUUID } from "crypto";
+import { join, resolve } from "path";
+var LocalFsProvider = class {
+  name = "local-fs";
+  dir;
+  ready = null;
+  constructor(dir) {
+    this.dir = resolve(dir);
+  }
+  ensureDir() {
+    if (!this.ready) this.ready = mkdir(this.dir, { recursive: true }).then(() => void 0);
+    return this.ready;
+  }
+  // Reject any ref that isn't a bare id, so a ref can never escape `dir`
+  // (path traversal). Ids we mint are UUIDs.
+  pathFor(ref) {
+    if (!/^[A-Za-z0-9_-]+$/.test(ref)) throw new Error("invalid storage ref");
+    return join(this.dir, ref);
+  }
+  async put({ bytes }) {
+    await this.ensureDir();
+    const ref = randomUUID();
+    await writeFile(this.pathFor(ref), bytes);
+    return { ref };
+  }
+  async get(ref) {
+    try {
+      const bytes = await readFile(this.pathFor(ref));
+      return { kind: "bytes", bytes };
+    } catch {
+      return null;
+    }
+  }
+  async delete(ref) {
+    await rm(this.pathFor(ref), { force: true });
+  }
+};
+export {
+  DbBlobProvider,
+  LocalFsProvider
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/providers/db-blob.ts","../src/providers/local-fs.ts"],"sourcesContent":["import type { IStoreAdapter } from '@fonderie/store';\n\nimport type { IFetched, IStorageProvider, IStoredRef } from './types';\n\n/**\n * Zero-infra provider: bytes live in Postgres (`fonderie_storage_blobs`, created\n * by this package's migration). Great for getting started and self-hosting — the\n * whole app is one Node process + one database, and a `pg_dump` captures the\n * objects atomically with the rows that reference them. Swap to `S3Provider`\n * when bandwidth or table size make object storage worth the extra moving part;\n * no consumer code changes, only the provider passed in config.\n */\nexport class DbBlobProvider implements IStorageProvider {\n\treadonly name = 'db-blob';\n\n\tconstructor(private readonly store: IStoreAdapter) {}\n\n\tasync put({ bytes }: { bytes: Uint8Array; contentType: string }): Promise<IStoredRef> {\n\t\tconst rows = await this.store.query<{ id: string }>(\n\t\t\t'INSERT INTO fonderie_storage_blobs (bytes) VALUES ($1) RETURNING id',\n\t\t\t[Buffer.from(bytes)],\n\t\t);\n\t\treturn { ref: rows[0]!.id };\n\t}\n\n\tasync get(ref: string): Promise<IFetched | null> {\n\t\tconst rows = await this.store.query<{ bytes: Buffer }>(\n\t\t\t'SELECT bytes FROM fonderie_storage_blobs WHERE id = $1',\n\t\t\t[ref],\n\t\t);\n\t\tconst row = rows[0];\n\t\treturn row ? { kind: 'bytes', bytes: row.bytes } : null;\n\t}\n\n\tasync delete(ref: string): Promise<void> {\n\t\tawait this.store.query('DELETE FROM fonderie_storage_blobs WHERE id = $1', [ref]);\n\t}\n}\n","import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';\nimport { randomUUID } from 'node:crypto';\nimport { join, resolve } from 'node:path';\n\nimport type { IFetched, IStorageProvider, IStoredRef } from './types';\n\n/**\n * Zero-infra provider: bytes live on the server's filesystem under `dir`. Useful\n * for a single-box deployment that wants objects off the database without\n * standing up object storage. The `ref` is an opaque filename; content type is\n * the consumer's concern, so nothing about the bytes-on-disk needs to encode it.\n *\n * Serves inline through the app like `DbBlobProvider` (no CDN in front), so at\n * real scale prefer `S3Provider` — same interface, one config line.\n */\nexport class LocalFsProvider implements IStorageProvider {\n\treadonly name = 'local-fs';\n\tprivate readonly dir: string;\n\tprivate ready: Promise<void> | null = null;\n\n\tconstructor(dir: string) {\n\t\tthis.dir = resolve(dir);\n\t}\n\n\tprivate ensureDir(): Promise<void> {\n\t\tif (!this.ready) this.ready = mkdir(this.dir, { recursive: true }).then(() => undefined);\n\t\treturn this.ready;\n\t}\n\n\t// Reject any ref that isn't a bare id, so a ref can never escape `dir`\n\t// (path traversal). Ids we mint are UUIDs.\n\tprivate pathFor(ref: string): string {\n\t\tif (!/^[A-Za-z0-9_-]+$/.test(ref)) throw new Error('invalid storage ref');\n\t\treturn join(this.dir, ref);\n\t}\n\n\tasync put({ bytes }: { bytes: Uint8Array; contentType: string }): Promise<IStoredRef> {\n\t\tawait this.ensureDir();\n\t\tconst ref = randomUUID();\n\t\tawait writeFile(this.pathFor(ref), bytes);\n\t\treturn { ref };\n\t}\n\n\tasync get(ref: string): Promise<IFetched | null> {\n\t\ttry {\n\t\t\tconst bytes = await readFile(this.pathFor(ref));\n\t\t\treturn { kind: 'bytes', bytes };\n\t\t} catch {\n\t\t\treturn null; // ENOENT (or an invalid ref) → treated as not found\n\t\t}\n\t}\n\n\tasync delete(ref: string): Promise<void> {\n\t\tawait rm(this.pathFor(ref), { force: true }); // force → no throw when already gone\n\t}\n}\n"],"mappings":";AAYO,IAAM,iBAAN,MAAiD;AAAA,EAGvD,YAA6B,OAAsB;AAAtB;AAAA,EAAuB;AAAA,EAAvB;AAAA,EAFpB,OAAO;AAAA,EAIhB,MAAM,IAAI,EAAE,MAAM,GAAoE;AACrF,UAAM,OAAO,MAAM,KAAK,MAAM;AAAA,MAC7B;AAAA,MACA,CAAC,OAAO,KAAK,KAAK,CAAC;AAAA,IACpB;AACA,WAAO,EAAE,KAAK,KAAK,CAAC,EAAG,GAAG;AAAA,EAC3B;AAAA,EAEA,MAAM,IAAI,KAAuC;AAChD,UAAM,OAAO,MAAM,KAAK,MAAM;AAAA,MAC7B;AAAA,MACA,CAAC,GAAG;AAAA,IACL;AACA,UAAM,MAAM,KAAK,CAAC;AAClB,WAAO,MAAM,EAAE,MAAM,SAAS,OAAO,IAAI,MAAM,IAAI;AAAA,EACpD;AAAA,EAEA,MAAM,OAAO,KAA4B;AACxC,UAAM,KAAK,MAAM,MAAM,oDAAoD,CAAC,GAAG,CAAC;AAAA,EACjF;AACD;;;ACrCA,SAAS,OAAO,UAAU,IAAI,iBAAiB;AAC/C,SAAS,kBAAkB;AAC3B,SAAS,MAAM,eAAe;AAavB,IAAM,kBAAN,MAAkD;AAAA,EAC/C,OAAO;AAAA,EACC;AAAA,EACT,QAA8B;AAAA,EAEtC,YAAY,KAAa;AACxB,SAAK,MAAM,QAAQ,GAAG;AAAA,EACvB;AAAA,EAEQ,YAA2B;AAClC,QAAI,CAAC,KAAK,MAAO,MAAK,QAAQ,MAAM,KAAK,KAAK,EAAE,WAAW,KAAK,CAAC,EAAE,KAAK,MAAM,MAAS;AACvF,WAAO,KAAK;AAAA,EACb;AAAA;AAAA;AAAA,EAIQ,QAAQ,KAAqB;AACpC,QAAI,CAAC,mBAAmB,KAAK,GAAG,EAAG,OAAM,IAAI,MAAM,qBAAqB;AACxE,WAAO,KAAK,KAAK,KAAK,GAAG;AAAA,EAC1B;AAAA,EAEA,MAAM,IAAI,EAAE,MAAM,GAAoE;AACrF,UAAM,KAAK,UAAU;AACrB,UAAM,MAAM,WAAW;AACvB,UAAM,UAAU,KAAK,QAAQ,GAAG,GAAG,KAAK;AACxC,WAAO,EAAE,IAAI;AAAA,EACd;AAAA,EAEA,MAAM,IAAI,KAAuC;AAChD,QAAI;AACH,YAAM,QAAQ,MAAM,SAAS,KAAK,QAAQ,GAAG,CAAC;AAC9C,aAAO,EAAE,MAAM,SAAS,MAAM;AAAA,IAC/B,QAAQ;AACP,aAAO;AAAA,IACR;AAAA,EACD;AAAA,EAEA,MAAM,OAAO,KAA4B;AACxC,UAAM,GAAG,KAAK,QAAQ,GAAG,GAAG,EAAE,OAAO,KAAK,CAAC;AAAA,EAC5C;AACD;","names":[]}

package/dist/migrations/index.d.ts

@@ -0,0 +1,3 @@
+declare const getMigrationsPath: () => string;
+
+export { getMigrationsPath };

package/dist/migrations/index.js

@@ -0,0 +1,7 @@
+// src/migrations/index.ts
+import { createMigrationsPath } from "@fonderie/store";
+var getMigrationsPath = () => createMigrationsPath(import.meta.url);
+export {
+  getMigrationsPath
+};
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/migrations/index.ts"],"sourcesContent":["import { createMigrationsPath } from '@fonderie/store';\n\nexport const getMigrationsPath = (): string => createMigrationsPath(import.meta.url);\n"],"mappings":";AAAA,SAAS,4BAA4B;AAE9B,IAAM,oBAAoB,MAAc,qBAAqB,YAAY,GAAG;","names":[]}

package/dist/migrations/sql/001_storage.sql

@@ -0,0 +1,19 @@
+-- ----------------------------------------------------------------------------
+-- 001_storage
+-- ----------------------------------------------------------------------------
+-- Byte storage for the built-in DbBlobProvider (zero-infra object storage in
+-- Postgres). `bytes` holds an arbitrary object; the id is the opaque `ref` the
+-- provider hands back and consumers persist. Untouched when an external
+-- provider (local-fs, S3/MinIO) is wired — the ref then points into that
+-- backend instead.
+--
+-- Deliberately content-agnostic: no content_type, no owner, no purpose. What an
+-- object *is* and who owns it is the consumer's concern (e.g. @fonderie/media
+-- keeps that in its own fonderie_media_assets table).
+-- ----------------------------------------------------------------------------
+
+CREATE TABLE IF NOT EXISTS fonderie_storage_blobs (
+	id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+	bytes       BYTEA       NOT NULL,
+	created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);

package/dist/s3.cjs

@@ -0,0 +1,70 @@
+"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/s3.ts
+var s3_exports = {};
+__export(s3_exports, {
+  S3Provider: () => S3Provider
+});
+module.exports = __toCommonJS(s3_exports);
+
+// src/providers/s3.ts
+var import_node_crypto = require("crypto");
+var import_client_s3 = require("@aws-sdk/client-s3");
+var import_s3_request_presigner = require("@aws-sdk/s3-request-presigner");
+var S3Provider = class {
+  name = "s3";
+  client;
+  bucket;
+  ttl;
+  prefix;
+  constructor(opts) {
+    this.bucket = opts.bucket;
+    this.ttl = opts.presignTtlSeconds ?? 300;
+    this.prefix = opts.keyPrefix ?? "";
+    this.client = new import_client_s3.S3Client({
+      region: opts.region ?? "us-east-1",
+      ...opts.endpoint ? { endpoint: opts.endpoint, forcePathStyle: opts.forcePathStyle ?? true } : {},
+      ...opts.accessKeyId && opts.secretAccessKey ? { credentials: { accessKeyId: opts.accessKeyId, secretAccessKey: opts.secretAccessKey } } : {}
+    });
+  }
+  async put({ bytes, contentType }) {
+    const ref = `${this.prefix}${(0, import_node_crypto.randomUUID)()}`;
+    await this.client.send(
+      new import_client_s3.PutObjectCommand({ Bucket: this.bucket, Key: ref, Body: bytes, ContentType: contentType })
+    );
+    return { ref };
+  }
+  async get(ref) {
+    const url = await (0, import_s3_request_presigner.getSignedUrl)(
+      this.client,
+      new import_client_s3.GetObjectCommand({ Bucket: this.bucket, Key: ref }),
+      { expiresIn: this.ttl }
+    );
+    return { kind: "redirect", url };
+  }
+  async delete(ref) {
+    await this.client.send(new import_client_s3.DeleteObjectCommand({ Bucket: this.bucket, Key: ref }));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  S3Provider
+});
+//# sourceMappingURL=s3.cjs.map

package/dist/s3.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/s3.ts","../src/providers/s3.ts"],"sourcesContent":["// Opt-in S3-compatible provider (AWS S3 / MinIO / R2 / B2 / Spaces). Imported\n// separately from the main entry so the AWS SDK peer is only loaded when used:\n//   import { S3Provider } from '@fonderie/storage/s3'\nexport { S3Provider } from './providers/s3';\nexport type { IS3ProviderOptions } from './providers/s3';\n","import { randomUUID } from 'node:crypto';\n\nimport {\n\tDeleteObjectCommand,\n\tGetObjectCommand,\n\tPutObjectCommand,\n\tS3Client,\n} from '@aws-sdk/client-s3';\nimport { getSignedUrl } from '@aws-sdk/s3-request-presigner';\n\nimport type { IFetched, IStorageProvider, IStoredRef } from './types';\n\nexport interface IS3ProviderOptions {\n\t/** Target bucket. Must already exist. */\n\tbucket: string;\n\tregion?: string;\n\t/**\n\t * Custom endpoint for S3-compatible services. Set this for MinIO / R2 / B2 /\n\t * Spaces (e.g. `http://localhost:9000`); omit for AWS S3. When set,\n\t * path-style addressing is enabled by default (what MinIO expects).\n\t */\n\tendpoint?: string;\n\tforcePathStyle?: boolean;\n\taccessKeyId?: string;\n\tsecretAccessKey?: string;\n\t/** How long a presigned GET URL stays valid, in seconds. Default 300. */\n\tpresignTtlSeconds?: number;\n\t/** Optional key prefix, e.g. 'avatars/' or 'archive/'. */\n\tkeyPrefix?: string;\n}\n\n/**\n * Object-storage provider for any S3-compatible service — AWS S3, **MinIO**,\n * Cloudflare R2, Backblaze B2, DigitalOcean Spaces. They're one provider\n * parameterized by `endpoint`; MinIO is just `endpoint: 'http://minio:9000'`.\n *\n * `get` returns a **presigned redirect URL** rather than bytes, so the app\n * hands the client straight to the object store / CDN and never proxies the\n * payload — the point of moving off DB blobs at scale.\n *\n * Requires the `@aws-sdk/client-s3` + `@aws-sdk/s3-request-presigner` optional\n * peers; import from `@fonderie/storage/s3` only when you actually use it, so\n * DbBlob / LocalFs consumers never pull the AWS SDK.\n */\nexport class S3Provider implements IStorageProvider {\n\treadonly name = 's3';\n\tprivate readonly client: S3Client;\n\tprivate readonly bucket: string;\n\tprivate readonly ttl: number;\n\tprivate readonly prefix: string;\n\n\tconstructor(opts: IS3ProviderOptions) {\n\t\tthis.bucket = opts.bucket;\n\t\tthis.ttl = opts.presignTtlSeconds ?? 300;\n\t\tthis.prefix = opts.keyPrefix ?? '';\n\t\tthis.client = new S3Client({\n\t\t\tregion: opts.region ?? 'us-east-1',\n\t\t\t...(opts.endpoint\n\t\t\t\t? { endpoint: opts.endpoint, forcePathStyle: opts.forcePathStyle ?? true }\n\t\t\t\t: {}),\n\t\t\t...(opts.accessKeyId && opts.secretAccessKey\n\t\t\t\t? { credentials: { accessKeyId: opts.accessKeyId, secretAccessKey: opts.secretAccessKey } }\n\t\t\t\t: {}),\n\t\t});\n\t}\n\n\tasync put({ bytes, contentType }: { bytes: Uint8Array; contentType: string }): Promise<IStoredRef> {\n\t\tconst ref = `${this.prefix}${randomUUID()}`;\n\t\tawait this.client.send(\n\t\t\tnew PutObjectCommand({ Bucket: this.bucket, Key: ref, Body: bytes, ContentType: contentType }),\n\t\t);\n\t\treturn { ref };\n\t}\n\n\tasync get(ref: string): Promise<IFetched | null> {\n\t\t// A presigned URL doesn't verify existence — a deleted key simply 404s at\n\t\t// the store when the client follows the redirect. Callers that hold their\n\t\t// own metadata row (e.g. media) have already confirmed the asset exists.\n\t\tconst url = await getSignedUrl(\n\t\t\tthis.client,\n\t\t\tnew GetObjectCommand({ Bucket: this.bucket, Key: ref }),\n\t\t\t{ expiresIn: this.ttl },\n\t\t);\n\t\treturn { kind: 'redirect', url };\n\t}\n\n\tasync delete(ref: string): Promise<void> {\n\t\tawait this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: ref }));\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,yBAA2B;AAE3B,uBAKO;AACP,kCAA6B;AAoCtB,IAAM,aAAN,MAA6C;AAAA,EAC1C,OAAO;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,MAA0B;AACrC,SAAK,SAAS,KAAK;AACnB,SAAK,MAAM,KAAK,qBAAqB;AACrC,SAAK,SAAS,KAAK,aAAa;AAChC,SAAK,SAAS,IAAI,0BAAS;AAAA,MAC1B,QAAQ,KAAK,UAAU;AAAA,MACvB,GAAI,KAAK,WACN,EAAE,UAAU,KAAK,UAAU,gBAAgB,KAAK,kBAAkB,KAAK,IACvE,CAAC;AAAA,MACJ,GAAI,KAAK,eAAe,KAAK,kBAC1B,EAAE,aAAa,EAAE,aAAa,KAAK,aAAa,iBAAiB,KAAK,gBAAgB,EAAE,IACxF,CAAC;AAAA,IACL,CAAC;AAAA,EACF;AAAA,EAEA,MAAM,IAAI,EAAE,OAAO,YAAY,GAAoE;AAClG,UAAM,MAAM,GAAG,KAAK,MAAM,OAAG,+BAAW,CAAC;AACzC,UAAM,KAAK,OAAO;AAAA,MACjB,IAAI,kCAAiB,EAAE,QAAQ,KAAK,QAAQ,KAAK,KAAK,MAAM,OAAO,aAAa,YAAY,CAAC;AAAA,IAC9F;AACA,WAAO,EAAE,IAAI;AAAA,EACd;AAAA,EAEA,MAAM,IAAI,KAAuC;AAIhD,UAAM,MAAM,UAAM;AAAA,MACjB,KAAK;AAAA,MACL,IAAI,kCAAiB,EAAE,QAAQ,KAAK,QAAQ,KAAK,IAAI,CAAC;AAAA,MACtD,EAAE,WAAW,KAAK,IAAI;AAAA,IACvB;AACA,WAAO,EAAE,MAAM,YAAY,IAAI;AAAA,EAChC;AAAA,EAEA,MAAM,OAAO,KAA4B;AACxC,UAAM,KAAK,OAAO,KAAK,IAAI,qCAAoB,EAAE,QAAQ,KAAK,QAAQ,KAAK,IAAI,CAAC,CAAC;AAAA,EAClF;AACD;","names":[]}

package/dist/s3.d.cts

@@ -0,0 +1,49 @@
+import { I as IStorageProvider, a as IStoredRef, b as IFetched } from './types-Cb480R4u.cjs';
+
+interface IS3ProviderOptions {
+    /** Target bucket. Must already exist. */
+    bucket: string;
+    region?: string;
+    /**
+     * Custom endpoint for S3-compatible services. Set this for MinIO / R2 / B2 /
+     * Spaces (e.g. `http://localhost:9000`); omit for AWS S3. When set,
+     * path-style addressing is enabled by default (what MinIO expects).
+     */
+    endpoint?: string;
+    forcePathStyle?: boolean;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    /** How long a presigned GET URL stays valid, in seconds. Default 300. */
+    presignTtlSeconds?: number;
+    /** Optional key prefix, e.g. 'avatars/' or 'archive/'. */
+    keyPrefix?: string;
+}
+/**
+ * Object-storage provider for any S3-compatible service — AWS S3, **MinIO**,
+ * Cloudflare R2, Backblaze B2, DigitalOcean Spaces. They're one provider
+ * parameterized by `endpoint`; MinIO is just `endpoint: 'http://minio:9000'`.
+ *
+ * `get` returns a **presigned redirect URL** rather than bytes, so the app
+ * hands the client straight to the object store / CDN and never proxies the
+ * payload — the point of moving off DB blobs at scale.
+ *
+ * Requires the `@aws-sdk/client-s3` + `@aws-sdk/s3-request-presigner` optional
+ * peers; import from `@fonderie/storage/s3` only when you actually use it, so
+ * DbBlob / LocalFs consumers never pull the AWS SDK.
+ */
+declare class S3Provider implements IStorageProvider {
+    readonly name = "s3";
+    private readonly client;
+    private readonly bucket;
+    private readonly ttl;
+    private readonly prefix;
+    constructor(opts: IS3ProviderOptions);
+    put({ bytes, contentType }: {
+        bytes: Uint8Array;
+        contentType: string;
+    }): Promise<IStoredRef>;
+    get(ref: string): Promise<IFetched | null>;
+    delete(ref: string): Promise<void>;
+}
+
+export { type IS3ProviderOptions, S3Provider };

package/dist/s3.d.ts

@@ -0,0 +1,49 @@
+import { I as IStorageProvider, a as IStoredRef, b as IFetched } from './types-Cb480R4u.js';
+
+interface IS3ProviderOptions {
+    /** Target bucket. Must already exist. */
+    bucket: string;
+    region?: string;
+    /**
+     * Custom endpoint for S3-compatible services. Set this for MinIO / R2 / B2 /
+     * Spaces (e.g. `http://localhost:9000`); omit for AWS S3. When set,
+     * path-style addressing is enabled by default (what MinIO expects).
+     */
+    endpoint?: string;
+    forcePathStyle?: boolean;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    /** How long a presigned GET URL stays valid, in seconds. Default 300. */
+    presignTtlSeconds?: number;
+    /** Optional key prefix, e.g. 'avatars/' or 'archive/'. */
+    keyPrefix?: string;
+}
+/**
+ * Object-storage provider for any S3-compatible service — AWS S3, **MinIO**,
+ * Cloudflare R2, Backblaze B2, DigitalOcean Spaces. They're one provider
+ * parameterized by `endpoint`; MinIO is just `endpoint: 'http://minio:9000'`.
+ *
+ * `get` returns a **presigned redirect URL** rather than bytes, so the app
+ * hands the client straight to the object store / CDN and never proxies the
+ * payload — the point of moving off DB blobs at scale.
+ *
+ * Requires the `@aws-sdk/client-s3` + `@aws-sdk/s3-request-presigner` optional
+ * peers; import from `@fonderie/storage/s3` only when you actually use it, so
+ * DbBlob / LocalFs consumers never pull the AWS SDK.
+ */
+declare class S3Provider implements IStorageProvider {
+    readonly name = "s3";
+    private readonly client;
+    private readonly bucket;
+    private readonly ttl;
+    private readonly prefix;
+    constructor(opts: IS3ProviderOptions);
+    put({ bytes, contentType }: {
+        bytes: Uint8Array;
+        contentType: string;
+    }): Promise<IStoredRef>;
+    get(ref: string): Promise<IFetched | null>;
+    delete(ref: string): Promise<void>;
+}
+
+export { type IS3ProviderOptions, S3Provider };

package/dist/s3.js

@@ -0,0 +1,48 @@
+// src/providers/s3.ts
+import { randomUUID } from "crypto";
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  PutObjectCommand,
+  S3Client
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+var S3Provider = class {
+  name = "s3";
+  client;
+  bucket;
+  ttl;
+  prefix;
+  constructor(opts) {
+    this.bucket = opts.bucket;
+    this.ttl = opts.presignTtlSeconds ?? 300;
+    this.prefix = opts.keyPrefix ?? "";
+    this.client = new S3Client({
+      region: opts.region ?? "us-east-1",
+      ...opts.endpoint ? { endpoint: opts.endpoint, forcePathStyle: opts.forcePathStyle ?? true } : {},
+      ...opts.accessKeyId && opts.secretAccessKey ? { credentials: { accessKeyId: opts.accessKeyId, secretAccessKey: opts.secretAccessKey } } : {}
+    });
+  }
+  async put({ bytes, contentType }) {
+    const ref = `${this.prefix}${randomUUID()}`;
+    await this.client.send(
+      new PutObjectCommand({ Bucket: this.bucket, Key: ref, Body: bytes, ContentType: contentType })
+    );
+    return { ref };
+  }
+  async get(ref) {
+    const url = await getSignedUrl(
+      this.client,
+      new GetObjectCommand({ Bucket: this.bucket, Key: ref }),
+      { expiresIn: this.ttl }
+    );
+    return { kind: "redirect", url };
+  }
+  async delete(ref) {
+    await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: ref }));
+  }
+};
+export {
+  S3Provider
+};
+//# sourceMappingURL=s3.js.map

package/dist/s3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/providers/s3.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\n\nimport {\n\tDeleteObjectCommand,\n\tGetObjectCommand,\n\tPutObjectCommand,\n\tS3Client,\n} from '@aws-sdk/client-s3';\nimport { getSignedUrl } from '@aws-sdk/s3-request-presigner';\n\nimport type { IFetched, IStorageProvider, IStoredRef } from './types';\n\nexport interface IS3ProviderOptions {\n\t/** Target bucket. Must already exist. */\n\tbucket: string;\n\tregion?: string;\n\t/**\n\t * Custom endpoint for S3-compatible services. Set this for MinIO / R2 / B2 /\n\t * Spaces (e.g. `http://localhost:9000`); omit for AWS S3. When set,\n\t * path-style addressing is enabled by default (what MinIO expects).\n\t */\n\tendpoint?: string;\n\tforcePathStyle?: boolean;\n\taccessKeyId?: string;\n\tsecretAccessKey?: string;\n\t/** How long a presigned GET URL stays valid, in seconds. Default 300. */\n\tpresignTtlSeconds?: number;\n\t/** Optional key prefix, e.g. 'avatars/' or 'archive/'. */\n\tkeyPrefix?: string;\n}\n\n/**\n * Object-storage provider for any S3-compatible service — AWS S3, **MinIO**,\n * Cloudflare R2, Backblaze B2, DigitalOcean Spaces. They're one provider\n * parameterized by `endpoint`; MinIO is just `endpoint: 'http://minio:9000'`.\n *\n * `get` returns a **presigned redirect URL** rather than bytes, so the app\n * hands the client straight to the object store / CDN and never proxies the\n * payload — the point of moving off DB blobs at scale.\n *\n * Requires the `@aws-sdk/client-s3` + `@aws-sdk/s3-request-presigner` optional\n * peers; import from `@fonderie/storage/s3` only when you actually use it, so\n * DbBlob / LocalFs consumers never pull the AWS SDK.\n */\nexport class S3Provider implements IStorageProvider {\n\treadonly name = 's3';\n\tprivate readonly client: S3Client;\n\tprivate readonly bucket: string;\n\tprivate readonly ttl: number;\n\tprivate readonly prefix: string;\n\n\tconstructor(opts: IS3ProviderOptions) {\n\t\tthis.bucket = opts.bucket;\n\t\tthis.ttl = opts.presignTtlSeconds ?? 300;\n\t\tthis.prefix = opts.keyPrefix ?? '';\n\t\tthis.client = new S3Client({\n\t\t\tregion: opts.region ?? 'us-east-1',\n\t\t\t...(opts.endpoint\n\t\t\t\t? { endpoint: opts.endpoint, forcePathStyle: opts.forcePathStyle ?? true }\n\t\t\t\t: {}),\n\t\t\t...(opts.accessKeyId && opts.secretAccessKey\n\t\t\t\t? { credentials: { accessKeyId: opts.accessKeyId, secretAccessKey: opts.secretAccessKey } }\n\t\t\t\t: {}),\n\t\t});\n\t}\n\n\tasync put({ bytes, contentType }: { bytes: Uint8Array; contentType: string }): Promise<IStoredRef> {\n\t\tconst ref = `${this.prefix}${randomUUID()}`;\n\t\tawait this.client.send(\n\t\t\tnew PutObjectCommand({ Bucket: this.bucket, Key: ref, Body: bytes, ContentType: contentType }),\n\t\t);\n\t\treturn { ref };\n\t}\n\n\tasync get(ref: string): Promise<IFetched | null> {\n\t\t// A presigned URL doesn't verify existence — a deleted key simply 404s at\n\t\t// the store when the client follows the redirect. Callers that hold their\n\t\t// own metadata row (e.g. media) have already confirmed the asset exists.\n\t\tconst url = await getSignedUrl(\n\t\t\tthis.client,\n\t\t\tnew GetObjectCommand({ Bucket: this.bucket, Key: ref }),\n\t\t\t{ expiresIn: this.ttl },\n\t\t);\n\t\treturn { kind: 'redirect', url };\n\t}\n\n\tasync delete(ref: string): Promise<void> {\n\t\tawait this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: ref }));\n\t}\n}\n"],"mappings":";AAAA,SAAS,kBAAkB;AAE3B;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACM;AACP,SAAS,oBAAoB;AAoCtB,IAAM,aAAN,MAA6C;AAAA,EAC1C,OAAO;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,MAA0B;AACrC,SAAK,SAAS,KAAK;AACnB,SAAK,MAAM,KAAK,qBAAqB;AACrC,SAAK,SAAS,KAAK,aAAa;AAChC,SAAK,SAAS,IAAI,SAAS;AAAA,MAC1B,QAAQ,KAAK,UAAU;AAAA,MACvB,GAAI,KAAK,WACN,EAAE,UAAU,KAAK,UAAU,gBAAgB,KAAK,kBAAkB,KAAK,IACvE,CAAC;AAAA,MACJ,GAAI,KAAK,eAAe,KAAK,kBAC1B,EAAE,aAAa,EAAE,aAAa,KAAK,aAAa,iBAAiB,KAAK,gBAAgB,EAAE,IACxF,CAAC;AAAA,IACL,CAAC;AAAA,EACF;AAAA,EAEA,MAAM,IAAI,EAAE,OAAO,YAAY,GAAoE;AAClG,UAAM,MAAM,GAAG,KAAK,MAAM,GAAG,WAAW,CAAC;AACzC,UAAM,KAAK,OAAO;AAAA,MACjB,IAAI,iBAAiB,EAAE,QAAQ,KAAK,QAAQ,KAAK,KAAK,MAAM,OAAO,aAAa,YAAY,CAAC;AAAA,IAC9F;AACA,WAAO,EAAE,IAAI;AAAA,EACd;AAAA,EAEA,MAAM,IAAI,KAAuC;AAIhD,UAAM,MAAM,MAAM;AAAA,MACjB,KAAK;AAAA,MACL,IAAI,iBAAiB,EAAE,QAAQ,KAAK,QAAQ,KAAK,IAAI,CAAC;AAAA,MACtD,EAAE,WAAW,KAAK,IAAI;AAAA,IACvB;AACA,WAAO,EAAE,MAAM,YAAY,IAAI;AAAA,EAChC;AAAA,EAEA,MAAM,OAAO,KAA4B;AACxC,UAAM,KAAK,OAAO,KAAK,IAAI,oBAAoB,EAAE,QAAQ,KAAK,QAAQ,KAAK,IAAI,CAAC,CAAC;AAAA,EAClF;AACD;","names":[]}

package/dist/types-Cb480R4u.d.cts

@@ -0,0 +1,46 @@
+/**
+ * The storage seam every backend implements — the same provider pattern
+ * @fonderie/billing uses for payment providers. Product code (media uploads, DB
+ * archives, anything) depends on this interface, never on a concrete backend,
+ * so `DbBlobProvider` (zero infra) → `S3Provider` (object storage / MinIO) is a
+ * one-line swap in the consumer's config.
+ *
+ * Deliberately content-agnostic and least-common-denominator: `put` / `get` /
+ * `delete` of raw bytes, nothing backend-specific and nothing about *what* the
+ * bytes are. The one real divergence between backends — "can you hand the client
+ * a URL, or must the app stream the bytes?" — is modelled by the discriminated
+ * result of `get`, so an S3 provider can return a presigned URL while a DB /
+ * filesystem provider returns bytes, and the caller never branches on which.
+ */
+/** A backend-opaque handle to a stored object; the consumer persists it verbatim. */
+interface IStoredRef {
+    ref: string;
+}
+/**
+ * The outcome of resolving a ref. `bytes` → the caller has the raw bytes (serve
+ * them / write them to a file / parse them). `redirect` → a URL the backend can
+ * serve directly (e.g. an S3 presigned URL) — hand it to the client. `null` →
+ * not found.
+ */
+type IFetched = {
+    kind: 'bytes';
+    bytes: Uint8Array;
+} | {
+    kind: 'redirect';
+    url: string;
+};
+interface IStorageProvider {
+    /** Stable id for logs/diagnostics (e.g. 'db-blob', 'local-fs', 's3'). */
+    readonly name: string;
+    /** Persist bytes; `contentType` is passed for backends that store it natively (S3). */
+    put(input: {
+        bytes: Uint8Array;
+        contentType: string;
+    }): Promise<IStoredRef>;
+    /** Resolve a ref to bytes or a redirect URL, or null if it's gone. */
+    get(ref: string): Promise<IFetched | null>;
+    /** Remove the stored object. Idempotent — deleting a missing ref must not throw. */
+    delete(ref: string): Promise<void>;
+}
+
+export type { IStorageProvider as I, IStoredRef as a, IFetched as b };

package/dist/types-Cb480R4u.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The storage seam every backend implements — the same provider pattern
+ * @fonderie/billing uses for payment providers. Product code (media uploads, DB
+ * archives, anything) depends on this interface, never on a concrete backend,
+ * so `DbBlobProvider` (zero infra) → `S3Provider` (object storage / MinIO) is a
+ * one-line swap in the consumer's config.
+ *
+ * Deliberately content-agnostic and least-common-denominator: `put` / `get` /
+ * `delete` of raw bytes, nothing backend-specific and nothing about *what* the
+ * bytes are. The one real divergence between backends — "can you hand the client
+ * a URL, or must the app stream the bytes?" — is modelled by the discriminated
+ * result of `get`, so an S3 provider can return a presigned URL while a DB /
+ * filesystem provider returns bytes, and the caller never branches on which.
+ */
+/** A backend-opaque handle to a stored object; the consumer persists it verbatim. */
+interface IStoredRef {
+    ref: string;
+}
+/**
+ * The outcome of resolving a ref. `bytes` → the caller has the raw bytes (serve
+ * them / write them to a file / parse them). `redirect` → a URL the backend can
+ * serve directly (e.g. an S3 presigned URL) — hand it to the client. `null` →
+ * not found.
+ */
+type IFetched = {
+    kind: 'bytes';
+    bytes: Uint8Array;
+} | {
+    kind: 'redirect';
+    url: string;
+};
+interface IStorageProvider {
+    /** Stable id for logs/diagnostics (e.g. 'db-blob', 'local-fs', 's3'). */
+    readonly name: string;
+    /** Persist bytes; `contentType` is passed for backends that store it natively (S3). */
+    put(input: {
+        bytes: Uint8Array;
+        contentType: string;
+    }): Promise<IStoredRef>;
+    /** Resolve a ref to bytes or a redirect URL, or null if it's gone. */
+    get(ref: string): Promise<IFetched | null>;
+    /** Remove the stored object. Idempotent — deleting a missing ref must not throw. */
+    delete(ref: string): Promise<void>;
+}
+
+export type { IStorageProvider as I, IStoredRef as a, IFetched as b };

package/package.json

@@ -0,0 +1,90 @@
+{
+	"name": "@fonderie/storage",
+	"version": "0.0.0",
+	"description": "Content-agnostic, provider-abstracted object storage — store any bytes on Postgres, disk, or S3-compatible object storage (S3/MinIO/R2) behind one interface. The low-dependency foundation for media, archives, and more.",
+	"keywords": [
+		"fonderiejs",
+		"storage",
+		"object-storage",
+		"s3",
+		"minio",
+		"blob",
+		"saas",
+		"typescript"
+	],
+	"license": "MIT",
+	"type": "module",
+	"engines": {
+		"node": ">=20"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		},
+		"./s3": {
+			"types": "./dist/s3.d.ts",
+			"import": "./dist/s3.js",
+			"require": "./dist/s3.cjs"
+		},
+		"./migrations": {
+			"types": "./dist/migrations/index.d.ts",
+			"import": "./dist/migrations/index.js"
+		}
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsup && tsup --config tsup.migrations.ts",
+		"dev": "tsup --watch",
+		"typecheck": "tsc --noEmit",
+		"test": "tsx --test src/__tests__/*.test.ts",
+		"lint": "biome lint src",
+		"format": "biome format --write src",
+		"check": "biome check --write src"
+	},
+	"peerDependencies": {
+		"@fonderie/core": "^0.8.0",
+		"@fonderie/store": "^0.2.0",
+		"@aws-sdk/client-s3": "^3.0.0",
+		"@aws-sdk/s3-request-presigner": "^3.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@aws-sdk/client-s3": {
+			"optional": true
+		},
+		"@aws-sdk/s3-request-presigner": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@aws-sdk/client-s3": "^3.0.0",
+		"@aws-sdk/s3-request-presigner": "^3.0.0",
+		"@fonderie/core": "../core",
+		"@fonderie/store": "../store",
+		"@types/node": "^26.4.1",
+		"tsup": "^8.5.1",
+		"tsx": "^4.23.13",
+		"typescript": "^6.0.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"brain",
+		"LICENSE",
+		"README.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/fonderiejs/fonderie.git",
+		"directory": "packages/storage"
+	},
+	"homepage": "https://github.com/fonderiejs/fonderie/tree/main/packages/storage#readme",
+	"bugs": {
+		"url": "https://github.com/fonderiejs/fonderie/issues"
+	}
+}