@tulip-systems/core 0.8.2 → 0.9.0

package/dist/src/modules/storage/lib/service.server.mjs

@@ -0,0 +1,514 @@
+import { ServerError } from "../../router/lib/error.server.mjs";
+import { generateDefaultUUID } from "../../database/lib/helpers.mjs";
+import { storageAssets } from "./schema.mjs";
+import { confirmUploadInputSchema, presignUploadInputSchema, uploadInputSchema } from "./validators.mjs";
+import { StorageAdapterError } from "../providers/lib/errors.mjs";
+import z from "zod";
+import { and, desc, eq, inArray, isNotNull, isNull } from "drizzle-orm";
+
+//#region src/modules/storage/lib/service.server.ts
+/**
+* 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,
+*     },
+*   }),
+* });
+*/
+var Storage = class Storage {
+	#adapter;
+	#db;
+	prefix;
+	constructor({ db, adapter, prefix }) {
+		this.#db = db;
+		this.#adapter = adapter;
+		this.prefix = prefix ?? "uploads";
+	}
+	/**
+	* 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(props) {
+		return new Storage(props);
+	}
+	/**
+	* 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"
+	*/
+	#generateKey(input) {
+		const id = z.uuid().parse(input);
+		return `${this.prefix}/${id}`;
+	}
+	/**
+	* 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) {
+		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();
+	}
+	/**
+	* 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);
+	* }
+	*/
+	async getAssetById(id) {
+		const parsedId = z.uuid().parse(id);
+		const [asset] = await this.getAssetByIdQuery(parsedId);
+		return asset ?? 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) {
+		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();
+	}
+	/**
+	* 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 getAssetByKey(key) {
+		const [result] = await this.getAssetByKeyQuery(key);
+		return result ?? 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() {
+		return this.#db.select().from(storageAssets).where(and(eq(storageAssets.provider, this.#adapter.key), eq(storageAssets.bucket, this.#adapter.bucketName), isNull(storageAssets.deletedAt))).orderBy(desc(storageAssets.createdAt)).$dynamic();
+	}
+	/**
+	* 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 listAssets() {
+		return await this.listAssetsQuery().limit(100) ?? [];
+	}
+	/**
+	* 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) {
+		const input = presignUploadInputSchema.parse(props);
+		const id = generateDefaultUUID();
+		const uploadId = input.uploadId ?? generateDefaultUUID();
+		const key = this.#generateKey(id);
+		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" });
+		try {
+			const presignedUrl = await this.#adapter.putObjectURL({
+				key,
+				contentType,
+				size,
+				metadata
+			});
+			return {
+				...record,
+				presignedUrl
+			};
+		} catch (error) {
+			await this.#db.update(storageAssets).set({ status: "error" }).where(eq(storageAssets.id, record.id));
+			throw this.#parseError(error, { fallbackMessage: "Failed to generate upload URL" });
+		}
+	}
+	/**
+	* 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) {
+		const uploadId = confirmUploadInputSchema.parse(props);
+		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);
+		if (!record) throw new ServerError("NOT_FOUND", { message: "Storage asset not found" });
+		if (record.status === "ready") return record;
+		let head;
+		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" });
+		}
+		const [updated] = await this.#db.update(storageAssets).set({
+			status: "ready",
+			uploadedAt: /* @__PURE__ */ 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;
+	}
+	/**
+	* 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 upload(props) {
+		const { body, contentType, size, metadata, name, visibility } = uploadInputSchema.parse(props);
+		const id = generateDefaultUUID();
+		const key = this.#generateKey(id);
+		const [record] = await this.#db.insert(storageAssets).values({
+			id,
+			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 record" });
+		try {
+			const uploaded = await this.#adapter.putObject({
+				key,
+				body,
+				contentType,
+				size,
+				metadata
+			});
+			const [updated] = await this.#db.update(storageAssets).set({
+				status: "ready",
+				uploadedAt: /* @__PURE__ */ 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 (!updated) throw new ServerError("INTERNAL_SERVER_ERROR", { message: "Failed to finalize upload" });
+			return updated;
+		} catch (error) {
+			await this.#db.update(storageAssets).set({ status: "error" }).where(and(eq(storageAssets.id, record.id), eq(storageAssets.status, "pending")));
+			throw this.#parseError(error, { fallbackMessage: "Failed to upload object" });
+		}
+	}
+	/**
+	* 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 getObject(input) {
+		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" });
+		return this.#adapter.getObject(record.key).catch((error) => {
+			throw this.#parseError(error, { fallbackMessage: "Failed to retrieve object" });
+		});
+	}
+	/**
+	* 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 getObjectURL(input, options) {
+		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" });
+		return this.#adapter.getObjectURL(record.key, options).catch((error) => {
+			throw this.#parseError(error, { fallbackMessage: "Failed to generate object URL" });
+		});
+	}
+	/**
+	* 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) {
+		const id = z.uuid().parse(input);
+		const [deleted] = await this.deleteAssets([id]);
+		return deleted ?? 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
+	*/
+	async deleteAssets(input) {
+		const ids = [...new Set(z.array(z.uuid()).parse(input))];
+		if (ids.length === 0) return [];
+		return this.#db.update(storageAssets).set({ deletedAt: /* @__PURE__ */ new Date() }).where(and(inArray(storageAssets.id, ids), eq(storageAssets.provider, this.#adapter.key), eq(storageAssets.bucket, this.#adapter.bucketName), isNull(storageAssets.deletedAt))).returning();
+	}
+	/**
+	* 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 restoreAsset(input) {
+		const id = z.uuid().parse(input);
+		const [restored] = await this.restoreAssets([id]);
+		return restored ?? null;
+	}
+	/**
+	* Restores multiple soft-deleted storage assets by clearing `deletedAt`.
+	*
+	* @param input - Storage asset ids (UUID[])
+	* @returns Restored asset records
+	*/
+	async restoreAssets(input) {
+		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();
+	}
+	/**
+	* 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) {
+		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) {
+		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" });
+		}
+		const deletedIds = records.map((r) => r.id);
+		return await this.#db.delete(storageAssets).where(and(inArray(storageAssets.id, deletedIds), eq(storageAssets.provider, this.#adapter.key), eq(storageAssets.bucket, this.#adapter.bucketName))).returning();
+	}
+	/**
+	* 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`
+	*/
+	#parseError(error, options) {
+		if (error instanceof ServerError) return error;
+		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
+			});
+		}
+		return new ServerError("INTERNAL_SERVER_ERROR", {
+			message: options?.fallbackMessage ?? "Unknown storage error",
+			cause: error instanceof Error ? error : void 0
+		});
+	}
+};
+
+//#endregion
+export { Storage };

package/dist/src/modules/storage/lib/upload.client.d.mts

@@ -0,0 +1,57 @@
+import { PresignUploadInput, PresignUploadOutput, SelectStorageAssetSchema } from "./validators.mjs";
+import { StorageRouterInputs, StorageRouterOutputs } from "./procedures.server.mjs";
+
+//#region src/modules/storage/lib/upload.client.d.ts
+/**
+ * Upload request
+ */
+type UploadFileRequest = PresignUploadInput & {
+  file: File;
+};
+type PrepareUploadInput = Omit<UploadFileRequest, "name" | "contentType" | "size">;
+type UploadHooks = {
+  beforePresign?: (input: UploadFileRequest) => Promise<void> | void;
+  afterPresign?: (presignResult: PresignUploadOutput) => Promise<void> | void;
+  beforeConfirm?: (presignResult: PresignUploadOutput) => Promise<void> | void;
+  afterConfirm?: (asset: SelectStorageAssetSchema) => Promise<void> | void;
+};
+/**
+ * Upload client
+ */
+type UploadClient = {
+  prepareUpload: (input: PrepareUploadInput) => UploadFileRequest;
+  upload: (input: UploadFileRequest, hooks?: UploadHooks) => Promise<SelectStorageAssetSchema>;
+  deleteAsset: (id: string) => Promise<SelectStorageAssetSchema | null>;
+  deleteAssets: (ids: string[]) => Promise<SelectStorageAssetSchema[]>;
+  restoreAsset: (id: string) => Promise<SelectStorageAssetSchema | null>;
+  restoreAssets: (ids: string[]) => Promise<SelectStorageAssetSchema[]>;
+  purgeAsset: (id: string) => Promise<SelectStorageAssetSchema | null>;
+  purgeAssets: (ids: string[]) => Promise<SelectStorageAssetSchema[]>;
+};
+/**
+ * Create upload client props
+ */
+type CreateStorageClientProps = {
+  endpoints: {
+    presign: (input: StorageRouterInputs["presign"]) => Promise<StorageRouterOutputs["presign"]>;
+    confirm: (uploadId: StorageRouterInputs["confirm"]) => Promise<StorageRouterOutputs["confirm"]>;
+    deleteAssets: (ids: StorageRouterInputs["deleteAssets"]) => Promise<StorageRouterOutputs["deleteAssets"]>;
+    deleteAsset: (id: StorageRouterInputs["deleteAsset"]) => Promise<StorageRouterOutputs["deleteAsset"]>;
+    restoreAsset: (id: StorageRouterInputs["restoreAsset"]) => Promise<StorageRouterOutputs["restoreAsset"]>;
+    restoreAssets: (ids: StorageRouterInputs["restoreAssets"]) => Promise<StorageRouterOutputs["restoreAssets"]>;
+    purgeAsset: (id: StorageRouterInputs["purgeAsset"]) => Promise<StorageRouterOutputs["purgeAsset"]>;
+    purgeAssets: (ids: StorageRouterInputs["purgeAssets"]) => Promise<StorageRouterOutputs["purgeAssets"]>;
+  };
+};
+/**
+ * Creates an upload client for the storage module.
+ *
+ * Flow:
+ * - Prepare upload payload with generated id and resolved key
+ * - Request presigned upload URL from server
+ * - Upload file bytes directly to object storage
+ * - Confirm upload and receive finalized storage asset
+ */
+declare function createUploadClient(props: CreateStorageClientProps): UploadClient;
+//#endregion
+export { PrepareUploadInput, UploadClient, UploadFileRequest, UploadHooks, createUploadClient };

package/dist/src/modules/storage/lib/upload.client.mjs

@@ -0,0 +1,86 @@
+//#region src/modules/storage/lib/upload.client.ts
+/**
+* Creates an upload client for the storage module.
+*
+* Flow:
+* - Prepare upload payload with generated id and resolved key
+* - Request presigned upload URL from server
+* - Upload file bytes directly to object storage
+* - Confirm upload and receive finalized storage asset
+*/
+function createUploadClient(props) {
+	/**
+	* Create input schema for the upload method
+	* @param {PrepareUploadInput} input
+	* @returns {UploadFileRequest}
+	*/
+	function prepareUpload(input) {
+		return {
+			...input,
+			uploadId: input.uploadId ?? crypto.randomUUID(),
+			name: input.file.name,
+			size: input.file.size,
+			contentType: input.file.type || "application/octet-stream"
+		};
+	}
+	/**
+	* Upload file to the server
+	* @param {UploadFileRequest} input
+	* @returns {Promise<SelectStorageAssetSchema>}
+	*/
+	async function upload(input, hooks) {
+		let presignResult = null;
+		try {
+			/**
+			* Presign
+			*/
+			await hooks?.beforePresign?.(input);
+			presignResult = await props.endpoints.presign(input);
+			await hooks?.afterPresign?.(presignResult);
+			/**
+			* Upload the file
+			*/
+			const uploadResponse = await fetch(presignResult.presignedUrl, {
+				method: "PUT",
+				headers: { "Content-Type": input.contentType || "application/octet-stream" },
+				body: input.file
+			});
+			if (!uploadResponse.ok) {
+				const message = await uploadResponse.text();
+				throw new Error(`Upload failed: ${message}`);
+			}
+			/**
+			* Confirm
+			*/
+			await hooks?.beforeConfirm?.(presignResult);
+			const asset = await props.endpoints.confirm(presignResult.uploadId);
+			await hooks?.afterConfirm?.(asset);
+			/**
+			* Return
+			*/
+			return asset;
+		} catch (err) {
+			console.error("Upload error: ", err);
+			/**
+			* Delete if upload failed
+			* */
+			if (presignResult) await props.endpoints.deleteAsset(presignResult.id).catch((deleteErr) => {
+				console.error("Failed to delete asset after upload error: ", deleteErr);
+			});
+			throw err;
+		}
+	}
+	return {
+		prepareUpload,
+		upload,
+		deleteAsset: props.endpoints.deleteAsset,
+		deleteAssets: props.endpoints.deleteAssets,
+		restoreAsset: props.endpoints.restoreAsset,
+		restoreAssets: props.endpoints.restoreAssets,
+		purgeAsset: props.endpoints.purgeAsset,
+		purgeAssets: props.endpoints.purgeAssets
+	};
+}
+
+//#endregion
+export { createUploadClient };