@tulip-systems/core 0.8.2 → 0.9.0

package/dist/src/modules/storage/lib/service.server.d.mts

@@ -0,0 +1,2217 @@
+import { TDatabaseSchema } from "../../database/lib/types.mjs";
+import { Database } from "../../database/lib/service.server.mjs";
+import { GetObjectURLOptions } from "../providers/lib/validators.mjs";
+import { StorageAdapter } from "../providers/lib/types.mjs";
+import { ConfirmUploadInput, PresignUploadInput, UploadInput } from "./validators.mjs";
+import * as drizzle_orm_pg_core0 from "drizzle-orm/pg-core";
+import * as node_stream0 from "node:stream";
+
+//#region src/modules/storage/lib/service.server.d.ts
+type StorageConfig<TSchema extends TDatabaseSchema> = {
+  db: Database<TSchema>;
+  adapter: StorageAdapter;
+  prefix?: string;
+};
+/**
+ * Storage service for working with asset metadata and object storage.
+ *
+ * Use `Storage.init()` to create a fully configured instance in app code.
+ *
+ * @param props - Storage configuration, including `db` and `adapter`
+ * @returns A ready-to-use `Storage` instance
+ * @example
+ * const storage = Storage.init({
+ *   db: drizzle(dbConnection),
+ *   adapter: new StorageS3Adapter({
+ *     bucketName: "my-app-uploads",
+ *     region: "us-east-1",
+ *     credentials: {
+ *       accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+ *       secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+ *     },
+ *   }),
+ * });
+ */
+declare class Storage<TSchema extends TDatabaseSchema> {
+  #private;
+  prefix: string;
+  private constructor();
+  /**
+   * Create a storage service instance.
+   *
+   * This keeps the public API aligned with other Tulip services such as
+   * `Database.init()`, `Email.init()`, and `Auth.init()`.
+   *
+   * @param props - Storage configuration, including `db` and `adapter`
+   * @returns A new `Storage` instance
+   * @example
+   * const storage = Storage.init({
+   *   db: drizzle(dbConnection),
+   *   adapter: new StorageS3Adapter({
+   *     bucketName: "my-app-uploads",
+   *     region: "us-east-1",
+   *     credentials: {
+   *       accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+   *       secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+   *     },
+   *   }),
+   * });
+   */
+  static init<TSchema extends TDatabaseSchema>(props: StorageConfig<TSchema>): Storage<TSchema>;
+  /**
+   * Builds a query to fetch a storage asset by its ID and the current adapter's provider.
+   * @param id - The asset ID to search for
+   * @returns A dynamic Drizzle query for fetching a single asset
+   * @example
+   * let query = storageService.getAssetByIdQuery("asset-123");
+   * query = query.where(eq(storageAssets.contentType, "image/png")); // Add additional conditions if needed
+   * const [asset] = await query;
+   */
+  getAssetByIdQuery(id: string): drizzle_orm_pg_core0.PgSelectBase<"storage_assets", {
+    provider: drizzle_orm_pg_core0.PgColumn<{
+      name: "provider";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: "s3";
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["s3"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    bucket: drizzle_orm_pg_core0.PgColumn<{
+      name: "bucket";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    key: drizzle_orm_pg_core0.PgColumn<{
+      name: "key";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    status: drizzle_orm_pg_core0.PgColumn<{
+      name: "status";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgEnumColumn";
+      data: "error" | "pending" | "ready";
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["pending", "ready", "error"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    visibility: drizzle_orm_pg_core0.PgColumn<{
+      name: "visibility";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgEnumColumn";
+      data: "private" | "public";
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["private", "public"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    size: drizzle_orm_pg_core0.PgColumn<{
+      name: "size";
+      tableName: "storage_assets";
+      dataType: "number";
+      columnType: "PgInteger";
+      data: number;
+      driverParam: string | number;
+      notNull: false;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    contentType: drizzle_orm_pg_core0.PgColumn<{
+      name: "contentType";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgVarchar";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      length: 255;
+    }>;
+    uploadId: drizzle_orm_pg_core0.PgColumn<{
+      name: "uploadId";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgUUID";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    name: drizzle_orm_pg_core0.PgColumn<{
+      name: "name";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    metadata: drizzle_orm_pg_core0.PgColumn<{
+      name: "metadata";
+      tableName: "storage_assets";
+      dataType: "json";
+      columnType: "PgJsonb";
+      data: unknown;
+      driverParam: unknown;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    etag: drizzle_orm_pg_core0.PgColumn<{
+      name: "etag";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    uploadedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "uploadedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    deletedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "deletedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    id: drizzle_orm_pg_core0.PgColumn<{
+      name: "id";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgUUID";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: true;
+      isAutoincrement: false;
+      hasRuntimeDefault: true;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    createdAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "createdAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    updatedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "updatedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+  }, "single", Record<"storage_assets", "not-null">, true, never, {
+    provider: "s3";
+    bucket: string;
+    key: string;
+    status: "error" | "pending" | "ready";
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    uploadId: string;
+    name: string | null;
+    metadata: unknown;
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+  }[], {
+    provider: drizzle_orm_pg_core0.PgColumn<{
+      name: "provider";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: "s3";
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["s3"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    bucket: drizzle_orm_pg_core0.PgColumn<{
+      name: "bucket";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    key: drizzle_orm_pg_core0.PgColumn<{
+      name: "key";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    status: drizzle_orm_pg_core0.PgColumn<{
+      name: "status";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgEnumColumn";
+      data: "error" | "pending" | "ready";
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["pending", "ready", "error"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    visibility: drizzle_orm_pg_core0.PgColumn<{
+      name: "visibility";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgEnumColumn";
+      data: "private" | "public";
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["private", "public"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    size: drizzle_orm_pg_core0.PgColumn<{
+      name: "size";
+      tableName: "storage_assets";
+      dataType: "number";
+      columnType: "PgInteger";
+      data: number;
+      driverParam: string | number;
+      notNull: false;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    contentType: drizzle_orm_pg_core0.PgColumn<{
+      name: "contentType";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgVarchar";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      length: 255;
+    }>;
+    uploadId: drizzle_orm_pg_core0.PgColumn<{
+      name: "uploadId";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgUUID";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    name: drizzle_orm_pg_core0.PgColumn<{
+      name: "name";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    metadata: drizzle_orm_pg_core0.PgColumn<{
+      name: "metadata";
+      tableName: "storage_assets";
+      dataType: "json";
+      columnType: "PgJsonb";
+      data: unknown;
+      driverParam: unknown;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    etag: drizzle_orm_pg_core0.PgColumn<{
+      name: "etag";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    uploadedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "uploadedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    deletedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "deletedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    id: drizzle_orm_pg_core0.PgColumn<{
+      name: "id";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgUUID";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: true;
+      isAutoincrement: false;
+      hasRuntimeDefault: true;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    createdAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "createdAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    updatedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "updatedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+  }>;
+  /**
+   * Fetches a storage asset by its ID.
+   * @param id - The asset ID to retrieve
+   * @returns The asset object if found, otherwise null
+   * @example
+   * const asset = await storageService.getAssetById("asset-123");
+   * if (asset) {
+   *   console.log(asset.key, asset.contentType);
+   * }
+   */
+  getAssetById(id: string): Promise<{
+    provider: "s3";
+    bucket: string;
+    key: string;
+    status: "error" | "pending" | "ready";
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    uploadId: string;
+    name: string | null;
+    metadata: unknown;
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+  } | null>;
+  /**
+   * Builds a query to fetch a single ready storage asset by key
+   * within the current adapter provider scope.
+   *
+   * Notes:
+   * - Scoped to `this.#adapter.key` to avoid cross-provider leakage.
+   * - Targets ready assets by default.
+   * - Uniqueness is expected on `(provider, bucket, key)`.
+   *
+   * @param key - The object key stored in `storage_assets.key`
+   * @returns A dynamic Drizzle query returning max 1 row
+   * @example
+   * let query = storageService.getAssetByKeyQuery("uploads/abc/main");
+   * query = query.leftJoin(otherTable, eq(otherTable.assetId, storageAssets.id));
+   * const [asset] = await query;
+   */
+  getAssetByKeyQuery(key: string): drizzle_orm_pg_core0.PgSelectBase<"storage_assets", {
+    provider: drizzle_orm_pg_core0.PgColumn<{
+      name: "provider";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: "s3";
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["s3"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    bucket: drizzle_orm_pg_core0.PgColumn<{
+      name: "bucket";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    key: drizzle_orm_pg_core0.PgColumn<{
+      name: "key";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    status: drizzle_orm_pg_core0.PgColumn<{
+      name: "status";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgEnumColumn";
+      data: "error" | "pending" | "ready";
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["pending", "ready", "error"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    visibility: drizzle_orm_pg_core0.PgColumn<{
+      name: "visibility";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgEnumColumn";
+      data: "private" | "public";
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["private", "public"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    size: drizzle_orm_pg_core0.PgColumn<{
+      name: "size";
+      tableName: "storage_assets";
+      dataType: "number";
+      columnType: "PgInteger";
+      data: number;
+      driverParam: string | number;
+      notNull: false;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    contentType: drizzle_orm_pg_core0.PgColumn<{
+      name: "contentType";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgVarchar";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      length: 255;
+    }>;
+    uploadId: drizzle_orm_pg_core0.PgColumn<{
+      name: "uploadId";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgUUID";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    name: drizzle_orm_pg_core0.PgColumn<{
+      name: "name";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    metadata: drizzle_orm_pg_core0.PgColumn<{
+      name: "metadata";
+      tableName: "storage_assets";
+      dataType: "json";
+      columnType: "PgJsonb";
+      data: unknown;
+      driverParam: unknown;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    etag: drizzle_orm_pg_core0.PgColumn<{
+      name: "etag";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    uploadedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "uploadedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    deletedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "deletedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    id: drizzle_orm_pg_core0.PgColumn<{
+      name: "id";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgUUID";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: true;
+      isAutoincrement: false;
+      hasRuntimeDefault: true;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    createdAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "createdAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    updatedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "updatedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+  }, "single", Record<"storage_assets", "not-null">, true, never, {
+    provider: "s3";
+    bucket: string;
+    key: string;
+    status: "error" | "pending" | "ready";
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    uploadId: string;
+    name: string | null;
+    metadata: unknown;
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+  }[], {
+    provider: drizzle_orm_pg_core0.PgColumn<{
+      name: "provider";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: "s3";
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["s3"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    bucket: drizzle_orm_pg_core0.PgColumn<{
+      name: "bucket";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    key: drizzle_orm_pg_core0.PgColumn<{
+      name: "key";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    status: drizzle_orm_pg_core0.PgColumn<{
+      name: "status";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgEnumColumn";
+      data: "error" | "pending" | "ready";
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["pending", "ready", "error"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    visibility: drizzle_orm_pg_core0.PgColumn<{
+      name: "visibility";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgEnumColumn";
+      data: "private" | "public";
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["private", "public"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    size: drizzle_orm_pg_core0.PgColumn<{
+      name: "size";
+      tableName: "storage_assets";
+      dataType: "number";
+      columnType: "PgInteger";
+      data: number;
+      driverParam: string | number;
+      notNull: false;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    contentType: drizzle_orm_pg_core0.PgColumn<{
+      name: "contentType";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgVarchar";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      length: 255;
+    }>;
+    uploadId: drizzle_orm_pg_core0.PgColumn<{
+      name: "uploadId";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgUUID";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    name: drizzle_orm_pg_core0.PgColumn<{
+      name: "name";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    metadata: drizzle_orm_pg_core0.PgColumn<{
+      name: "metadata";
+      tableName: "storage_assets";
+      dataType: "json";
+      columnType: "PgJsonb";
+      data: unknown;
+      driverParam: unknown;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    etag: drizzle_orm_pg_core0.PgColumn<{
+      name: "etag";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    uploadedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "uploadedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    deletedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "deletedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    id: drizzle_orm_pg_core0.PgColumn<{
+      name: "id";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgUUID";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: true;
+      isAutoincrement: false;
+      hasRuntimeDefault: true;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    createdAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "createdAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    updatedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "updatedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+  }>;
+  /**
+   * Fetches a single ready storage asset by key.
+   *
+   * This is the convenience wrapper around `getAssetByKeyQuery`.
+   * Use this when you only need the result, not query composition.
+   *
+   * @param key - Asset key to look up
+   * @returns The matching asset or `null` if none is found
+   * @example
+   * const asset = await storageService.getAssetByKey("uploads/abc/main");
+   * if (!asset) return;
+   */
+  getAssetByKey(key: string): Promise<{
+    provider: "s3";
+    bucket: string;
+    key: string;
+    status: "error" | "pending" | "ready";
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    uploadId: string;
+    name: string | null;
+    metadata: unknown;
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+  } | null>;
+  /**
+   * Builds a base query for listing storage assets.
+   *
+   * Scope and defaults:
+   * - Scoped to the current adapter provider (`this.#adapter.key`)
+   * - Orders by newest first (`createdAt DESC`)
+   *
+   * This method returns a dynamic query so callers can extend it with
+   * custom filters, joins, pagination, and limits.
+   *
+   * @returns A dynamic Drizzle query for listing assets
+   * @example
+   * const query = storageService
+   *   .listAssetsQuery()
+   *   .limit(50);
+   * const assets = await query;
+   */
+  listAssetsQuery(): drizzle_orm_pg_core0.PgSelectBase<"storage_assets", {
+    provider: drizzle_orm_pg_core0.PgColumn<{
+      name: "provider";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: "s3";
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["s3"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    bucket: drizzle_orm_pg_core0.PgColumn<{
+      name: "bucket";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    key: drizzle_orm_pg_core0.PgColumn<{
+      name: "key";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    status: drizzle_orm_pg_core0.PgColumn<{
+      name: "status";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgEnumColumn";
+      data: "error" | "pending" | "ready";
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["pending", "ready", "error"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    visibility: drizzle_orm_pg_core0.PgColumn<{
+      name: "visibility";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgEnumColumn";
+      data: "private" | "public";
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["private", "public"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    size: drizzle_orm_pg_core0.PgColumn<{
+      name: "size";
+      tableName: "storage_assets";
+      dataType: "number";
+      columnType: "PgInteger";
+      data: number;
+      driverParam: string | number;
+      notNull: false;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    contentType: drizzle_orm_pg_core0.PgColumn<{
+      name: "contentType";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgVarchar";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      length: 255;
+    }>;
+    uploadId: drizzle_orm_pg_core0.PgColumn<{
+      name: "uploadId";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgUUID";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    name: drizzle_orm_pg_core0.PgColumn<{
+      name: "name";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    metadata: drizzle_orm_pg_core0.PgColumn<{
+      name: "metadata";
+      tableName: "storage_assets";
+      dataType: "json";
+      columnType: "PgJsonb";
+      data: unknown;
+      driverParam: unknown;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    etag: drizzle_orm_pg_core0.PgColumn<{
+      name: "etag";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    uploadedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "uploadedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    deletedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "deletedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    id: drizzle_orm_pg_core0.PgColumn<{
+      name: "id";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgUUID";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: true;
+      isAutoincrement: false;
+      hasRuntimeDefault: true;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    createdAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "createdAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    updatedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "updatedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+  }, "single", Record<"storage_assets", "not-null">, true, never, {
+    provider: "s3";
+    bucket: string;
+    key: string;
+    status: "error" | "pending" | "ready";
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    uploadId: string;
+    name: string | null;
+    metadata: unknown;
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+  }[], {
+    provider: drizzle_orm_pg_core0.PgColumn<{
+      name: "provider";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: "s3";
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["s3"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    bucket: drizzle_orm_pg_core0.PgColumn<{
+      name: "bucket";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    key: drizzle_orm_pg_core0.PgColumn<{
+      name: "key";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    status: drizzle_orm_pg_core0.PgColumn<{
+      name: "status";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgEnumColumn";
+      data: "error" | "pending" | "ready";
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["pending", "ready", "error"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    visibility: drizzle_orm_pg_core0.PgColumn<{
+      name: "visibility";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgEnumColumn";
+      data: "private" | "public";
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["private", "public"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    size: drizzle_orm_pg_core0.PgColumn<{
+      name: "size";
+      tableName: "storage_assets";
+      dataType: "number";
+      columnType: "PgInteger";
+      data: number;
+      driverParam: string | number;
+      notNull: false;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    contentType: drizzle_orm_pg_core0.PgColumn<{
+      name: "contentType";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgVarchar";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      length: 255;
+    }>;
+    uploadId: drizzle_orm_pg_core0.PgColumn<{
+      name: "uploadId";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgUUID";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    name: drizzle_orm_pg_core0.PgColumn<{
+      name: "name";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    metadata: drizzle_orm_pg_core0.PgColumn<{
+      name: "metadata";
+      tableName: "storage_assets";
+      dataType: "json";
+      columnType: "PgJsonb";
+      data: unknown;
+      driverParam: unknown;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    etag: drizzle_orm_pg_core0.PgColumn<{
+      name: "etag";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgText";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    uploadedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "uploadedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    deletedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "deletedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    id: drizzle_orm_pg_core0.PgColumn<{
+      name: "id";
+      tableName: "storage_assets";
+      dataType: "string";
+      columnType: "PgUUID";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: true;
+      isAutoincrement: false;
+      hasRuntimeDefault: true;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    createdAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "createdAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    updatedAt: drizzle_orm_pg_core0.PgColumn<{
+      name: "updatedAt";
+      tableName: "storage_assets";
+      dataType: "date";
+      columnType: "PgTimestamp";
+      data: Date;
+      driverParam: string;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+  }>;
+  /**
+   * Lists storage assets using safe default pagination.
+   *
+   * This is the convenience wrapper around `listAssetsQuery`.
+   * Use `listAssetsQuery()` directly when you need custom query composition.
+   *
+   * @returns Up to 100 storage assets sorted by newest first
+   * @example
+   * const assets = await storageService.listAssets();
+   */
+  listAssets(): Promise<{
+    provider: "s3";
+    bucket: string;
+    key: string;
+    status: "error" | "pending" | "ready";
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    uploadId: string;
+    name: string | null;
+    metadata: unknown;
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+  }[]>;
+  /**
+   * Creates a pending storage asset record and generates a presigned upload URL.
+   *
+   * Flow:
+   * - Validates the input payload
+   * - Inserts a `pending` asset in the catalog (`storage_assets`)
+   * - Requests a presigned PUT URL from the storage adapter
+   * - Marks the asset as `error` if URL generation fails
+   *
+   * This method is intended for direct-to-storage browser uploads.
+   * The upload should be finalized later via a confirm step.
+   *
+   * @param props - Presign upload input (contentType, size, metadata)
+   * @returns The created asset id, key, and presigned URL
+   * @throws {ServerError} If intent creation or URL generation fails
+   * @example
+   * const result = await storageService.presignUpload({
+   *   contentType: "image/png",
+   *   size: 120_000,
+   *   metadata: { uploadToken: crypto.randomUUID() },
+   * });
+   * // result => { id, uploadId, key, presignedUrl }
+   */
+  presignUpload(props: PresignUploadInput): Promise<{
+    presignedUrl: string;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string | null;
+    key: string;
+    metadata: unknown;
+    provider: "s3";
+    uploadId: string;
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    bucket: string;
+    status: "error" | "pending" | "ready";
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+  }>;
+  /**
+   * Confirms a direct-to-storage upload by verifying object existence
+   * and transitioning the asset from `pending` to `ready`.
+   *
+   * Flow:
+   * - Validates confirm input
+   * - Loads the asset record scoped to the current adapter provider
+   * - Returns early if asset is already `ready` (idempotent behavior)
+   * - Verifies object existence/metadata via `adapter.headObject`
+   * - Marks asset as `error` if verification fails
+   * - Updates status to `ready` and stores upload metadata
+   *
+   * @param props - Confirm upload payload containing the asset uploadId
+   * @returns The updated storage asset record
+   * @throws {ServerError} If the asset is missing, verification fails, or update fails
+   * @example
+   * const asset = await storageService.confirmUpload("019d0051-2c0d-741e-9e3c-e5a5bc4d16a2");
+   * // asset.status === "ready"
+   */
+  confirmUpload(props: ConfirmUploadInput): Promise<{
+    provider: "s3";
+    bucket: string;
+    key: string;
+    status: "error" | "pending" | "ready";
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    uploadId: string;
+    name: string | null;
+    metadata: unknown;
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+  }>;
+  /**
+   * Uploads an asset directly from the server and persists its catalog record.
+   *
+   * Flow:
+   * - Validates upload input
+   * - Creates a `pending` asset record in `storage_assets`
+   * - Uploads the object bytes through the storage adapter
+   * - Marks the record as `ready` and stores upload metadata
+   * - Marks the record as `error` if upload fails
+   *
+   * This method is intended for server-side uploads (non-presigned flow).
+   * For browser direct uploads, use `presignUpload` + `confirmUpload`.
+   *
+   * @param props - Upload payload (body, contentType, size)
+   * @returns The finalized storage asset record
+   * @throws {ServerError} If record creation, upload, or finalization fails
+   * @example
+   * const asset = await storageService.upload({
+   *   body: fileBuffer,
+   *   contentType: "application/pdf",
+   *   size: fileBuffer.byteLength,
+   * });
+   */
+  upload(props: UploadInput): Promise<{
+    provider: "s3";
+    bucket: string;
+    key: string;
+    status: "error" | "pending" | "ready";
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    uploadId: string;
+    name: string | null;
+    metadata: unknown;
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+  }>;
+  /**
+   * Retrieves the object content for a ready storage asset.
+   *
+   * Flow:
+   * - Looks up the asset record by id, scoped to the current adapter provider
+   * - Ensures the asset is in `ready` status
+   * - Fetches object content from the storage adapter using the stored key
+   *
+   * @param id - The storage asset id
+   * @returns The adapter object response (stream/body + metadata)
+   * @throws {ServerError} If the asset does not exist or is not ready
+   * @example
+   * const object = await storageService.getObject("asset-123");
+   * // object.body can be streamed/consumed by caller
+   */
+  getObject(input: string): Promise<{
+    body: node_stream0.Readable;
+    contentType?: string | null | undefined;
+    size?: number | null | undefined;
+    metadata?: Record<string, string> | undefined;
+  }>;
+  /**
+   * Generates a presigned read URL for a ready storage asset.
+   *
+   * Flow:
+   * - Validates the asset id
+   * - Resolves the asset record scoped to the current adapter provider
+   * - Ensures the asset is in `ready` status
+   * - Delegates URL signing to the storage adapter using the stored key
+   *
+   * @param input - Storage asset id (UUID)
+   * @param options - Optional URL options (for example expiration/disposition)
+   * @returns A presigned URL for reading the object
+   * @throws {ServerError} If the asset does not exist or is not ready
+   * @example
+   * const url = await storageService.getObjectURL("019d0051-2c0d-741e-9e3c-e5a5bc4d16a2", {
+   *   expiresIn: 3600,
+   * });
+   */
+  getObjectURL(input: string, options?: GetObjectURLOptions): Promise<string>;
+  /**
+   * Soft deletes a single storage asset by id.
+   *
+   * This is a convenience wrapper around `deleteAssets`.
+   *
+   * @param input - Storage asset id (UUID)
+   * @returns The soft-deleted asset record, or null if not found/already deleted
+   */
+  deleteAsset(input: string): Promise<{
+    provider: "s3";
+    bucket: string;
+    key: string;
+    status: "error" | "pending" | "ready";
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    uploadId: string;
+    name: string | null;
+    metadata: unknown;
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+  } | null>;
+  /**
+   * Soft deletes multiple storage assets by setting `deletedAt`.
+   *
+   * Flow:
+   * - Validates and de-duplicates ids
+   * - Resolves provider-scoped active records
+   * - Marks matching rows as deleted by setting `deletedAt`
+   *
+   * @param input - Storage asset ids (UUID[])
+   * @returns Soft-deleted asset records
+   */
+  deleteAssets(input: string[]): Promise<{
+    provider: "s3";
+    bucket: string;
+    key: string;
+    status: "error" | "pending" | "ready";
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    uploadId: string;
+    name: string | null;
+    metadata: unknown;
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+  }[]>;
+  /**
+   * Restores a single soft-deleted storage asset.
+   *
+   * This is a convenience wrapper around `restoreAssets`.
+   *
+   * @param input - Storage asset id (UUID)
+   * @returns The restored asset record, or null if not found/not deleted
+   */
+  restoreAsset(input: string): Promise<{
+    provider: "s3";
+    bucket: string;
+    key: string;
+    status: "error" | "pending" | "ready";
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    uploadId: string;
+    name: string | null;
+    metadata: unknown;
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+  } | null>;
+  /**
+   * Restores multiple soft-deleted storage assets by clearing `deletedAt`.
+   *
+   * @param input - Storage asset ids (UUID[])
+   * @returns Restored asset records
+   */
+  restoreAssets(input: string[]): Promise<{
+    provider: "s3";
+    bucket: string;
+    key: string;
+    status: "error" | "pending" | "ready";
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    uploadId: string;
+    name: string | null;
+    metadata: unknown;
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+  }[]>;
+  /**
+   * Hard deletes a single storage asset.
+   *
+   * This is a convenience wrapper around `purgeAssets`.
+   *
+   * @param input - Storage asset id (UUID)
+   * @returns The purged asset record, or null if not found
+   */
+  purgeAsset(input: string): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string | null;
+    key: string;
+    metadata: unknown;
+    provider: "s3";
+    uploadId: string;
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    bucket: string;
+    status: "error" | "pending" | "ready";
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+  } | null>;
+  /**
+   * Hard deletes multiple storage assets.
+   *
+   * Flow:
+   * - Validates and de-duplicates ids
+   * - Resolves provider-scoped records
+   * - Deletes physical objects from the adapter by key
+   * - Hard deletes DB records
+   *
+   * @param input - Storage asset ids (UUID[])
+   * @returns Purged asset records
+   * @throws {ServerError} If provider deletion fails
+   */
+  purgeAssets(input: string[]): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string | null;
+    key: string;
+    metadata: unknown;
+    provider: "s3";
+    uploadId: string;
+    visibility: "private" | "public";
+    size: number | null;
+    contentType: string | null;
+    bucket: string;
+    status: "error" | "pending" | "ready";
+    etag: string | null;
+    uploadedAt: Date;
+    deletedAt: Date | null;
+  }[]>;
+}
+//#endregion
+export { Storage, StorageConfig };