@tulip-systems/core 0.7.0 → 0.8.1

package/src/modules/storage/lib/service.server.ts

@@ -1,490 +1,752 @@
-import {
-  DeleteObjectsCommand,
-  GetObjectCommand,
-  PutObjectCommand,
-  S3Client,
-  type S3ClientConfig,
-} from "@aws-sdk/client-s3";
-import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
-import { addSeconds } from "date-fns";
-import { and, asc, eq, inArray, isNotNull, isNull, type SQL } from "drizzle-orm";
-import { after } from "next/server";
-import { BUCKET_NAME } from "@/lib/config/constants";
-import { generateDefaultUUID, type TDatabaseSchema } from "@/modules/config/entry";
-import type { DatabaseClient } from "@/modules/config/entry.server";
-import {
-  convertOrderByToQueryParams,
-  convertSearchToQueryParams,
-} from "@/modules/data-tables/entry.server";
-import type { BulkActionSchema } from "@/modules/router/entry";
+import { and, desc, eq, inArray, isNotNull, isNull } from "drizzle-orm";
+import z from "zod";
+import { generateDefaultUUID } from "@/modules/database/lib/helpers";
+import type { Database } from "@/modules/database/lib/service.server";
+import type { TDatabaseSchema } from "@/modules/database/lib/types";
 import { ServerError } from "@/modules/router/lib/error.server";
-import { deviceSizes } from "./constants";
-import { getDriveBucketKey, inferNodeSubtype, isFile, isFolder } from "./helpers";
-import { nodePresignedUrls, nodes, nodeVariants } from "./schema";
+import { StorageAdapterError } from "../providers/lib/errors";
+import type { StorageAdapter } from "../providers/lib/types";
+import type { GetObjectURLOptions } from "../providers/lib/validators";
+import { storageAssets } from "./schema";
 import {
-  type CreateFolderNodeSchema,
-  type FileNode,
-  type GetFileURLSchema,
-  type GetNodesByParentIdInput,
-  type GetObjectInput,
-  getFileURLSchemaDefaults,
-  getObjectSchema,
-  type Node,
-  type PresignFileSchema,
-  type PutObjectInput,
-  putObjectSchema,
-  type UpdateNodeSchema,
-  type UploadFileSchema,
+  type ConfirmUploadInput,
+  confirmUploadInputSchema,
+  type PresignUploadInput,
+  presignUploadInputSchema,
+  type UploadInput,
+  uploadInputSchema,
 } from "./validators";
 
-/**
- * Storage Service Config
- */
-export type StorageServiceConfig<TSchema extends TDatabaseSchema> = {
-  db: DatabaseClient<TSchema>;
-  config: S3ClientConfig;
+export type StorageConfig<TSchema extends TDatabaseSchema> = {
+  db: Database<TSchema>;
+  adapter: StorageAdapter;
+  prefix?: string;
 };
 
 /**
- * Storage Service
+ * 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,
+ *     },
+ *   }),
+ * });
  */
-export class StorageService<TSchema extends TDatabaseSchema> {
-  /**
-   * S3 Client
-   */
-  #blob: S3Client;
-  #db: DatabaseClient<TSchema>;
 
-  /**
-   * Constructor
-   */
-  constructor({ db, config }: StorageServiceConfig<TSchema>) {
+export class Storage<TSchema extends TDatabaseSchema> {
+  #adapter: StorageAdapter;
+  #db: Database<TSchema>;
+  prefix: string;
+
+  private constructor({ db, adapter, prefix }: StorageConfig<TSchema>) {
     this.#db = db;
-    this.#blob = new S3Client(config);
+    this.#adapter = adapter;
+    this.prefix = prefix ?? "uploads";
   }
 
   /**
-   * Get Blob
+   * 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,
+   *     },
+   *   }),
+   * });
    */
-  blob() {
-    return this.#blob;
+  static init<TSchema extends TDatabaseSchema>(props: StorageConfig<TSchema>) {
+    return new Storage(props);
   }
 
   /**
-   * Create get command
+   * Generates the canonical object key for a storage asset id.
+   *
+   * This keeps bucket key structure internal to the storage service,
+   * so callers only work with asset ids and do not manage object paths.
+   *
+   * @param input - Storage asset id (UUID)
+   * @returns Canonical storage key (e.g. `uploads/<id>`)
+   * @example
+   * const key = this.#generateKey("019d0051-2c0d-741e-9e3c-e5a5bc4d16a2");
+   * // key => "uploads/019d0051-2c0d-741e-9e3c-e5a5bc4d16a2"
    */
-  #createGetCommand(props: GetObjectInput) {
-    const input = getObjectSchema.parse(props);
-
-    return new GetObjectCommand({
-      Bucket: BUCKET_NAME,
-      Key: getDriveBucketKey(input.id, input.variant),
-      ResponseContentDisposition: input.disposition,
-    });
+  #generateKey(input: string) {
+    const id = z.uuid().parse(input);
+    return `${this.prefix}/${id}`;
   }
 
   /**
-   * Get object
+   * 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;
    */
-  async getObject(id: string, options: GetFileURLSchema = getFileURLSchemaDefaults) {
-    const getCommand = this.#createGetCommand({ ...options, id });
-
-    return await this.#blob.send(getCommand);
+  getAssetByIdQuery(id: string) {
+    return this.#db
+      .select()
+      .from(storageAssets)
+      .where(
+        and(
+          eq(storageAssets.id, id),
+          eq(storageAssets.provider, this.#adapter.key),
+          eq(storageAssets.bucket, this.#adapter.bucketName),
+          isNull(storageAssets.deletedAt),
+        ),
+      )
+      .limit(1)
+      .$dynamic();
   }
 
   /**
-   * Create put command
+   * 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);
+   * }
    */
-  #createPutCommand(props: PutObjectInput) {
-    const input = putObjectSchema.parse(props);
-
-    return new PutObjectCommand({
-      Bucket: BUCKET_NAME,
-      Key: getDriveBucketKey(input.id, input.variant),
-      Body: input.body,
-      ContentType: input.contentType ?? undefined,
-      ContentLength: input.size ?? undefined,
-      Metadata: {
-        nodeId: input.id,
-      },
-    });
+  async getAssetById(id: string) {
+    const parsedId = z.uuid().parse(id);
+    const [asset] = await this.getAssetByIdQuery(parsedId);
+    return asset ?? null;
   }
 
   /**
-   * Put object
+   * 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;
    */
-  async #putObject(props: PutObjectInput) {
-    const putCommand = this.#createPutCommand(props);
-    return await this.#blob.send(putCommand);
+  getAssetByKeyQuery(key: string) {
+    return this.#db
+      .select()
+      .from(storageAssets)
+      .where(
+        and(
+          eq(storageAssets.key, key),
+          eq(storageAssets.provider, this.#adapter.key),
+          eq(storageAssets.bucket, this.#adapter.bucketName),
+          eq(storageAssets.status, "ready"),
+          isNull(storageAssets.deletedAt),
+        ),
+      )
+      .limit(1)
+      .$dynamic();
   }
 
   /**
-   * Get node by id
+   * 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;
    */
-  async getNodeById(id: string) {
-    return this.#db.select().from(nodes).where(eq(nodes.id, id));
+  async getAssetByKey(key: string) {
+    const [result] = await this.getAssetByKeyQuery(key);
+    return result ?? null;
   }
 
   /**
-   * Get nodes by parent id
+   * 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;
    */
-  async getNodesByParentId({ filters, ...query }: GetNodesByParentIdInput) {
-    const orderBy = convertOrderByToQueryParams(query, nodes, asc(nodes.createdAt));
-    const search = convertSearchToQueryParams(query, [nodes.name]);
-
+  listAssetsQuery() {
     return this.#db
       .select()
-      .from(nodes)
+      .from(storageAssets)
       .where(
         and(
-          filters.nodeIds != null ? inArray(nodes.id, filters.nodeIds) : undefined,
-          filters.types != null ? inArray(nodes.type, filters.types) : undefined,
-          filters.isDeleted != null ? eq(nodes.isDeleted, filters.isDeleted) : undefined,
-          filters.isOrphaned === true
-            ? isNotNull(nodes.orphanedAt)
-            : filters.isOrphaned === false
-              ? isNull(nodes.orphanedAt)
-              : undefined,
-          filters.hidden != null ? eq(nodes.hidden, filters.hidden) : undefined,
-          filters.parentId ? eq(nodes.parentId, filters.parentId) : isNull(nodes.parentId),
-          eq(nodes.namespace, filters.namespace),
-          search,
+          eq(storageAssets.provider, this.#adapter.key),
+          eq(storageAssets.bucket, this.#adapter.bucketName),
+          isNull(storageAssets.deletedAt),
         ),
       )
-      .orderBy(orderBy as SQL);
+      .orderBy(desc(storageAssets.createdAt))
+      .$dynamic();
   }
 
   /**
-   * Get file url
+   * 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();
    */
-  async getSignedURL(node: Node, options: GetFileURLSchema = getFileURLSchemaDefaults) {
-    const [presignedUrl] = await this.#db
-      .select({ url: nodePresignedUrls.url, expiresAt: nodePresignedUrls.expiresAt })
-      .from(nodePresignedUrls)
-      .where(
-        and(
-          eq(nodePresignedUrls.nodeId, node.id),
-          eq(nodePresignedUrls.variant, options.variant),
-          eq(nodePresignedUrls.disposition, options.disposition),
-        ),
-      );
+  async listAssets() {
+    const assets = await this.listAssetsQuery().limit(100);
+    return assets ?? [];
+  }
 
-    if (presignedUrl && presignedUrl.expiresAt > new Date()) return presignedUrl.url;
+  /**
+   * 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 }
+   */
+  async presignUpload(props: PresignUploadInput) {
+    const input = presignUploadInputSchema.parse(props);
 
-    const expiresIn = 3600 * 24;
+    const id = generateDefaultUUID();
+    const uploadId = input.uploadId ?? generateDefaultUUID();
+    const key = this.#generateKey(id);
 
-    // Get the variants
-    const variants = await this.#db
-      .select()
-      .from(nodeVariants)
-      .where(eq(nodeVariants.nodeId, node.id));
-
-    // If the requested variant does not exist, fallback to main
-    const variantExists = variants.find((v) => v.variant === options.variant);
-    const variant = variantExists ? options.variant : "main";
-
-    console.info(
-      `Generating new signed url for file: ${node.id} with variant: ${variant} and disposition: ${options.disposition}`,
-    );
-
-    // Generate the get command
-    const getCommand = this.#createGetCommand({
-      id: node.id,
-      variant,
-      disposition: `${options.disposition}; filename="${node.name}"`,
-    });
+    const { contentType, size, metadata, name, visibility } = input;
+
+    const [record] = await this.#db
+      .insert(storageAssets)
+      .values({
+        id,
+        uploadId,
+        key,
+        size,
+        contentType,
+        name,
+        visibility,
+        provider: this.#adapter.key,
+        bucket: this.#adapter.bucketName,
+        status: "pending",
+        metadata,
+      })
+      .returning();
+
+    if (!record) {
+      throw new ServerError("INTERNAL_SERVER_ERROR", {
+        message: "Failed to create upload intent",
+      });
+    }
 
-    // Generate the presigned url that expires in 24 hours
-    const url = await getSignedUrl(this.#blob, getCommand, { expiresIn });
+    try {
+      const presignedUrl = await this.#adapter.putObjectURL({ key, contentType, size, metadata });
 
-    // Add the presigned url to the database
-    after(async () => {
+      return { ...record, presignedUrl };
+    } catch (error) {
       await this.#db
-        .insert(nodePresignedUrls)
-        .values({
-          nodeId: node.id,
-          url,
-          variant,
-          disposition: options.disposition,
-          expiresAt: addSeconds(new Date(), expiresIn),
-        })
-        .onConflictDoUpdate({
-          target: [
-            nodePresignedUrls.nodeId,
-            nodePresignedUrls.variant,
-            nodePresignedUrls.disposition,
-          ],
-          set: { url, expiresAt: addSeconds(new Date(), expiresIn) },
-        });
-    });
+        .update(storageAssets)
+        .set({ status: "error" })
+        .where(eq(storageAssets.id, record.id));
 
-    return url;
+      throw this.#parseError(error, {
+        fallbackMessage: "Failed to generate upload URL",
+      });
+    }
   }
 
   /**
-   * Upload file to S3 and add it to the database
-   **/
-  async uploadFile(input: UploadFileSchema & Pick<PutObjectInput, "body">) {
-    const id = input.id ?? generateDefaultUUID();
-
-    return await this.#db.transaction(async (tx) => {
-      const [result] = await tx
-        .insert(nodes)
-        .values({
-          id,
-          type: "file",
-          name: input.name,
-          namespace: input.namespace,
-          parentId: input.parentId,
-          size: input.size,
-          contentType: input.contentType,
-          mode: input.mode,
-          subtype: inferNodeSubtype(input),
-        })
-        .returning();
+   * 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"
+   */
+  async confirmUpload(props: ConfirmUploadInput) {
+    const uploadId = confirmUploadInputSchema.parse(props);
 
-      if (!result) {
-        throw new ServerError("INTERNAL_SERVER_ERROR", {
-          message: "Oep! Er is iets fout gegaan",
-        });
-      }
+    const [record] = await this.#db
+      .select()
+      .from(storageAssets)
+      .where(
+        and(
+          eq(storageAssets.uploadId, uploadId),
+          eq(storageAssets.provider, this.#adapter.key),
+          eq(storageAssets.bucket, this.#adapter.bucketName),
+          isNull(storageAssets.deletedAt),
+        ),
+      )
+      .limit(1);
 
-      await this.#putObject({
-        id,
-        body: input.body,
-        variant: "main",
-        name: input.name,
-        contentType: input.contentType,
-        size: input.size,
+    if (!record) {
+      throw new ServerError("NOT_FOUND", { message: "Storage asset not found" });
+    }
+
+    if (record.status === "ready") return record;
+
+    let head: Awaited<ReturnType<StorageAdapter["headObject"]>>;
+
+    try {
+      head = await this.#adapter.headObject({ key: record.key });
+    } catch (error) {
+      await this.#db
+        .update(storageAssets)
+        .set({ status: "error" })
+        .where(eq(storageAssets.id, record.id));
+
+      throw this.#parseError(error, {
+        fallbackMessage: "Failed to verify uploaded object",
       });
+    }
 
-      return result;
-    });
+    const [updated] = await this.#db
+      .update(storageAssets)
+      .set({
+        status: "ready",
+        uploadedAt: new Date(),
+        size: head.size ?? record.size,
+        contentType: head.contentType ?? record.contentType,
+      })
+      .where(and(eq(storageAssets.id, record.id), eq(storageAssets.status, "pending")))
+      .returning();
+
+    if (!updated) {
+      throw new ServerError("INTERNAL_SERVER_ERROR", { message: "Failed to confirm upload" });
+    }
+
+    return updated;
   }
 
   /**
-   * Presign a new upload
+   * 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,
+   * });
    */
-  async presignUpload(input: PresignFileSchema) {
-    // Generate the put command
-    const putCommand = this.#createPutCommand({
-      id: input.id,
-      name: input.name,
-      variant: "main",
-      contentType: input.contentType,
-      size: input.size,
-    });
+  async upload(props: UploadInput) {
+    const { body, contentType, size, metadata, name, visibility } = uploadInputSchema.parse(props);
 
-    // Generate the presigned url
-    const presignedUrl = await getSignedUrl(this.#blob, putCommand, { expiresIn: 3600 });
+    const id = generateDefaultUUID();
+    const key = this.#generateKey(id);
 
-    const [node] = await this.#db
-      .insert(nodes)
+    const [record] = await this.#db
+      .insert(storageAssets)
       .values({
-        ...input,
-        subtype: inferNodeSubtype(input),
-        isPending: true,
-        type: "file",
-        id: input.id,
+        id,
+        key,
+        size,
+        contentType,
+        name,
+        visibility,
+        provider: this.#adapter.key,
+        bucket: this.#adapter.bucketName,
+        status: "pending",
+        metadata,
       })
       .returning();
 
-    if (!node) {
+    if (!record) {
       throw new ServerError("INTERNAL_SERVER_ERROR", {
-        message: "Oep! Er is iets fout gegaan",
+        message: "Failed to create upload record",
       });
     }
 
-    // Return the result
-    return { id: input.id, presignedUrl, node };
-  }
+    try {
+      const uploaded = await this.#adapter.putObject({ key, body, contentType, size, metadata });
 
-  /**
-   * Confirm a new upload
-   */
-  async confirmUpload(input: { id: string }) {
-    const [result] = await this.#db
-      .update(nodes)
-      .set({ isPending: false })
-      .where(eq(nodes.id, input.id))
-      .returning();
+      const [updated] = await this.#db
+        .update(storageAssets)
+        .set({
+          status: "ready",
+          uploadedAt: new Date(),
+          size: uploaded.size ?? size ?? record.size,
+          contentType: uploaded.contentType ?? contentType ?? record.contentType,
+        })
+        .where(and(eq(storageAssets.id, record.id), eq(storageAssets.status, "pending")))
+        .returning();
 
-    if (!result) {
-      throw new ServerError("NOT_FOUND", { message: "File not found" });
-    }
+      if (!updated) {
+        throw new ServerError("INTERNAL_SERVER_ERROR", {
+          message: "Failed to finalize upload",
+        });
+      }
 
-    /**
-     * Generate the preview version of the file
-     */
-    // after(async () => {});
-    await this.generatePreviews(input);
+      return updated;
+    } catch (error) {
+      await this.#db
+        .update(storageAssets)
+        .set({ status: "error" })
+        .where(and(eq(storageAssets.id, record.id), eq(storageAssets.status, "pending")));
 
-    return result as FileNode;
+      throw this.#parseError(error, {
+        fallbackMessage: "Failed to upload object",
+      });
+    }
   }
 
   /**
-   * Generate preview version of the file
+   * 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
    */
-  async generatePreviews(input: { id: string }) {
-    /**
-     * Get the main version of the file
-     */
-    const getCommand = this.#createGetCommand({ id: input.id, variant: "main" });
-
-    const response = await this.#blob.send(getCommand);
-    const contentType = response.ContentType;
-    if (!response.Body) {
-      throw new ServerError("INTERNAL_SERVER_ERROR", {
-        message: "Oep! Er is iets fout gegaan",
-      });
-    }
+  async getObject(input: string) {
+    const id = z.uuid().parse(input);
 
-    /**
-     * Transform the main version of the file to a buffer
-     */
-    const byteArray = await response.Body.transformToByteArray();
-    const buffer = Buffer.from(byteArray);
-
-    /**
-     * Generate the preview versions for images
-     */
-    if (contentType?.startsWith("image/")) {
-      const sharp = await import("sharp");
-
-      // Generate the preview versions
-      await Promise.allSettled(
-        deviceSizes.flatMap(async (width) => {
-          // Generate the preview
-          const preview = await sharp.default(buffer).resize({ width }).webp().toBuffer();
-
-          // Upload the preview and add the variant to the database
-          return this.#db.transaction(async (tx) => {
-            await this.#putObject({
-              id: input.id,
-              body: preview,
-              variant: `preview-${width}`,
-              contentType: "image/webp",
-              size: preview.byteLength,
-            });
-
-            await tx.insert(nodeVariants).values({
-              nodeId: input.id,
-              variant: `preview-${width}`,
-              width,
-            });
-          });
-        }),
-      );
+    const [record] = await this.#db
+      .select()
+      .from(storageAssets)
+      .where(
+        and(
+          eq(storageAssets.id, id),
+          eq(storageAssets.provider, this.#adapter.key),
+          eq(storageAssets.bucket, this.#adapter.bucketName),
+          eq(storageAssets.status, "ready"),
+          isNull(storageAssets.deletedAt),
+        ),
+      )
+      .limit(1);
+
+    if (!record) {
+      throw new ServerError("NOT_FOUND", { message: "Storage asset not found" });
     }
+
+    return this.#adapter.getObject(record.key).catch((error) => {
+      throw this.#parseError(error, {
+        fallbackMessage: "Failed to retrieve object",
+      });
+    });
   }
 
   /**
-   * Create a new folder
+   * 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,
+   * });
    */
-  async createFolder(input: CreateFolderNodeSchema) {
-    const [parent] = input.parentId
-      ? await this.#db.select().from(nodes).where(eq(nodes.id, input.parentId))
-      : [];
-
-    /**
-     * Validate
-     */
-    if (input.parentId && !parent) {
-      throw new ServerError("BAD_REQUEST", { message: "Parent not found" });
-    }
 
-    if (parent && !isFolder(parent)) {
-      throw new ServerError("BAD_REQUEST", { message: "Parent is not a folder" });
+  async getObjectURL(input: string, options?: GetObjectURLOptions) {
+    const id = z.uuid().parse(input);
+
+    const [record] = await this.#db
+      .select()
+      .from(storageAssets)
+      .where(
+        and(
+          eq(storageAssets.id, id),
+          eq(storageAssets.provider, this.#adapter.key),
+          eq(storageAssets.bucket, this.#adapter.bucketName),
+          eq(storageAssets.status, "ready"),
+          isNull(storageAssets.deletedAt),
+        ),
+      )
+      .limit(1);
+
+    if (!record) {
+      throw new ServerError("NOT_FOUND", { message: "Storage asset not found" });
     }
 
-    if (parent && parent.namespace !== input.namespace) {
-      throw new ServerError("BAD_REQUEST", {
-        message: "Parent is not in the same namespace",
+    return this.#adapter.getObjectURL(record.key, options).catch((error) => {
+      throw this.#parseError(error, {
+        fallbackMessage: "Failed to generate object URL",
       });
-    }
+    });
+  }
 
-    /**
-     * Create the folder
-     */
-    const [result] = await this.#db
-      .insert(nodes)
-      .values({ ...input, type: "folder" })
-      .returning();
+  /**
+   * 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
+   */
+  async deleteAsset(input: string) {
+    const id = z.uuid().parse(input);
+    const [deleted] = await this.deleteAssets([id]);
+    return deleted ?? null;
+  }
 
-    if (!result) {
-      throw new ServerError("INTERNAL_SERVER_ERROR", {
-        message: "Folder kon niet worden aangemaakt",
-      });
-    }
+  /**
+   * 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
+   */
+  async deleteAssets(input: string[]) {
+    const ids = [...new Set(z.array(z.uuid()).parse(input))];
+    if (ids.length === 0) return [];
 
-    return result;
+    return this.#db
+      .update(storageAssets)
+      .set({ deletedAt: new Date() })
+      .where(
+        and(
+          inArray(storageAssets.id, ids),
+          eq(storageAssets.provider, this.#adapter.key),
+          eq(storageAssets.bucket, this.#adapter.bucketName),
+          isNull(storageAssets.deletedAt),
+        ),
+      )
+      .returning();
   }
 
   /**
-   * Update a node
+   * 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
    */
-  async updateNode(input: { id: string; data: UpdateNodeSchema }) {
-    const [node] = await this.#db
-      .select({ readonly: nodes.readonly })
-      .from(nodes)
-      .where(eq(nodes.id, input.id));
-
-    if (node?.readonly) {
-      throw new ServerError("BAD_REQUEST", { message: "Node is readonly" });
-    }
+  async restoreAsset(input: string) {
+    const id = z.uuid().parse(input);
+    const [restored] = await this.restoreAssets([id]);
+    return restored ?? null;
+  }
 
-    const [result] = await this.#db
-      .update(nodes)
-      .set(input.data)
-      .where(eq(nodes.id, input.id))
+  /**
+   * Restores multiple soft-deleted storage assets by clearing `deletedAt`.
+   *
+   * @param input - Storage asset ids (UUID[])
+   * @returns Restored asset records
+   */
+  async restoreAssets(input: string[]) {
+    const ids = [...new Set(z.array(z.uuid()).parse(input))];
+    if (ids.length === 0) return [];
+
+    return this.#db
+      .update(storageAssets)
+      .set({ deletedAt: null })
+      .where(
+        and(
+          inArray(storageAssets.id, ids),
+          eq(storageAssets.provider, this.#adapter.key),
+          eq(storageAssets.bucket, this.#adapter.bucketName),
+          isNotNull(storageAssets.deletedAt),
+        ),
+      )
       .returning();
+  }
 
-    if (!result) {
-      throw new ServerError("INTERNAL_SERVER_ERROR", {
-        message: "Node kon niet worden gewijzigd",
+  /**
+   * 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
+   */
+  async purgeAsset(input: string) {
+    const id = z.uuid().parse(input);
+    const [deleted] = await this.purgeAssets([id]);
+    return deleted ?? 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
+   */
+  async purgeAssets(input: string[]) {
+    const ids = [...new Set(z.array(z.uuid()).parse(input))];
+    if (ids.length === 0) return [];
+
+    const records = await this.#db
+      .select({
+        id: storageAssets.id,
+        key: storageAssets.key,
+      })
+      .from(storageAssets)
+      .where(
+        and(
+          inArray(storageAssets.id, ids),
+          eq(storageAssets.provider, this.#adapter.key),
+          eq(storageAssets.bucket, this.#adapter.bucketName),
+        ),
+      );
+
+    if (records.length === 0) return [];
+
+    const keys = records.map((r) => r.key);
+
+    try {
+      await this.#adapter.deleteObjects(keys);
+    } catch (error) {
+      throw this.#parseError(error, {
+        fallbackMessage: "Failed to delete storage objects",
       });
     }
 
-    return result;
+    const deletedIds = records.map((r) => r.id);
+
+    const deleted = await this.#db
+      .delete(storageAssets)
+      .where(
+        and(
+          inArray(storageAssets.id, deletedIds),
+          eq(storageAssets.provider, this.#adapter.key),
+          eq(storageAssets.bucket, this.#adapter.bucketName),
+        ),
+      )
+      .returning();
+
+    return deleted;
   }
 
   /**
-   * Delete nodes
+   * Normalizes unknown adapter/service errors into a consistent `ServerError`.
+   *
+   * Behavior:
+   * - Returns existing `ServerError` instances unchanged
+   * - Maps known storage adapter errors to application-level server errors
+   * - Falls back to a generic internal server error for unknown failures
+   *
+   * This keeps adapter-specific errors inside the storage layer while exposing
+   * a stable error contract to route handlers and RPC procedures.
+   *
+   * @param error - The unknown error to normalize
+   * @param options - Optional fallback message for non-specific failures
+   * @returns A normalized `ServerError`
    */
-  async deleteNodes(input: BulkActionSchema) {
-    const items = await this.#db
-      .select({ id: nodes.id, type: nodes.type, readonly: nodes.readonly })
-      .from(nodes)
-      .where(inArray(nodes.id, input.ids));
-
-    // Check if the nodes are readonly
-    if (items.some((item) => item.readonly)) {
-      throw new ServerError("BAD_REQUEST", { message: "Nodes are readonly" });
+
+  #parseError(error: unknown, options?: { fallbackMessage: string }) {
+    // If it's already a ServerError, return as-is to avoid double-wrapping
+    if (error instanceof ServerError) return error;
+
+    // Handle known storage adapter errors and convert to appropriate ServerError
+    if (error instanceof StorageAdapterError) {
+      if (error.code === "OBJECT_NOT_FOUND") {
+        return new ServerError("NOT_FOUND", {
+          message: "Storage asset not found",
+          cause: error,
+        });
+      }
+
+      return new ServerError("INTERNAL_SERVER_ERROR", {
+        message: options?.fallbackMessage ?? "Storage adapter error",
+        cause: error,
+      });
     }
 
-    // Split the nodes into folders and files
-    const folders = items.filter(isFolder).map((folder) => folder.id);
-    const files = items.filter(isFile).map((file) => file.id);
-
-    // Delete command for S3
-    const deleteCommand =
-      files.length > 0
-        ? new DeleteObjectsCommand({
-            Bucket: BUCKET_NAME,
-            Delete: {
-              Objects: files.map((id) => ({ Key: id })),
-            },
-          })
-        : undefined;
-
-    /**
-     * Delete files and folders in a transaction
-     */
-    await this.#db.transaction(async (tx) => {
-      await tx.delete(nodes).where(inArray(nodes.id, folders));
-      await tx.delete(nodes).where(inArray(nodes.id, files));
-
-      if (deleteCommand) await this.#blob.send(deleteCommand);
+    // For unknown errors, return a generic server error with limited information to avoid leaking details
+    return new ServerError("INTERNAL_SERVER_ERROR", {
+      message: options?.fallbackMessage ?? "Unknown storage error",
+      cause: error instanceof Error ? error : undefined,
     });
   }
 }