@tulip-systems/drive-local 0.11.1

package/dist/root/lib/router.server.mjs

@@ -0,0 +1,87 @@
+import { createLocalDriveFolderInputSchema, getLocalDriveNodesByParentIdInputSchema, getLocalFileURLSchema, listLocalDriveFlatInputSchema, listLocalDriveTreeInputSchema, localDriveFileNodeSchema, localDriveFlatResponseSchema, localDriveNodeParentSchema, localDriveNodeSchema, localDriveNodeWithChildrenSchema, localDrivePresignUploadOutputSchema, localDriveTreeResponseSchema, presignLocalDriveFileInputSchema, updateLocalDriveNodeInputSchema } from "./validators.mjs";
+import { bulkActionSchema } from "@tulip-systems/query";
+import { z as z$1 } from "zod";
+import { oc } from "@orpc/contract";
+//#region src/root/lib/router.server.ts
+/**
+* Local Drive router contract defines the input and output schemas for local drive-related procedures.
+*/
+const localDriveRouterContract = {
+	/**
+	* Get node with children
+	*/
+	getNodeWithChildren: oc.input(z$1.object({
+		id: z$1.string(),
+		namespace: z$1.string()
+	})).output(localDriveNodeWithChildrenSchema.nullable()),
+	/**
+	* Get folders by parent id
+	*/
+	getNodesByParentId: oc.input(getLocalDriveNodesByParentIdInputSchema).output(z$1.array(localDriveNodeSchema)),
+	/**
+	* List tree nodes with pagination and search.
+	*/
+	listTree: oc.input(listLocalDriveTreeInputSchema).output(localDriveTreeResponseSchema),
+	/**
+	* List flat nodes with pagination and search.
+	*/
+	listFlat: oc.input(listLocalDriveFlatInputSchema).output(localDriveFlatResponseSchema),
+	/**
+	* Get parents of a folder
+	*/
+	getFolderParents: oc.input(z$1.object({
+		id: z$1.string().nullable(),
+		namespace: z$1.string()
+	})).output(z$1.array(localDriveNodeParentSchema)),
+	/**
+	* Get url for opening a file
+	*/
+	getURL: oc.input(getLocalFileURLSchema.extend({ id: z$1.string() })).output(z$1.string().nullable()),
+	/**
+	* Create a direct upload intent for a file
+	*/
+	presignUpload: oc.input(presignLocalDriveFileInputSchema).output(localDrivePresignUploadOutputSchema),
+	/**
+	* Confirm a direct upload intent
+	*/
+	confirmUpload: oc.input(z$1.object({ uploadId: z$1.string() })).output(localDriveFileNodeSchema),
+	/**
+	* Create a folder
+	*/
+	createFolder: oc.input(createLocalDriveFolderInputSchema).output(localDriveNodeSchema),
+	/**
+	* Update node
+	*/
+	updateNode: oc.input(z$1.object({
+		id: z$1.string(),
+		data: updateLocalDriveNodeInputSchema
+	})).output(localDriveNodeSchema),
+	/**
+	* Set readonly
+	*/
+	setReadonly: oc.input(bulkActionSchema.extend({ readonly: z$1.boolean() })).output(z$1.array(localDriveNodeSchema)),
+	/**
+	* Move node
+	*/
+	moveNode: oc.input(z$1.object({
+		id: z$1.string(),
+		parentId: z$1.string().nullish()
+	})).output(localDriveNodeSchema),
+	/**
+	* Archive nodes
+	*/
+	archiveNodes: oc.input(bulkActionSchema).output(z$1.array(localDriveNodeSchema)),
+	/**
+	* Restore nodes
+	*/
+	restoreNodes: oc.input(bulkActionSchema).output(z$1.array(localDriveNodeSchema)),
+	/**
+	* Delete nodes
+	*/
+	deleteNodes: oc.input(bulkActionSchema).output(z$1.void())
+};
+/**
+* Create Drive base procedures
+*/
+//#endregion
+export { localDriveRouterContract };

package/dist/root/lib/search-params.d.mts

@@ -0,0 +1,15 @@
+//#region src/root/lib/search-params.d.ts
+declare const localDriveTreeFilterSearchParams: {
+  readonly search: import("nuqs/server").SingleParserBuilder<string>;
+  readonly types: import("nuqs/server").SingleParserBuilder<("folder" | "file")[]>;
+  readonly contentTypes: import("nuqs/server").SingleParserBuilder<string[]>;
+  readonly nodeIds: import("nuqs/server").SingleParserBuilder<string[]>;
+  readonly assetIds: import("nuqs/server").SingleParserBuilder<string[]>;
+  readonly namespace: import("nuqs/server").SingleParserBuilder<string>;
+  readonly parentId: import("nuqs/server").SingleParserBuilder<string | null>;
+  readonly subtypes: import("nuqs/server").SingleParserBuilder<("image" | "document" | "spreadsheet" | "video" | "audio" | "archive" | "other")[]>;
+  readonly isArchived: import("nuqs/server").SingleParserBuilder<boolean>;
+  readonly hidden: import("nuqs/server").SingleParserBuilder<boolean>;
+};
+//#endregion
+export { localDriveTreeFilterSearchParams };

package/dist/root/lib/search-params.mjs

@@ -0,0 +1,6 @@
+import { localDriveFilters } from "../config/filters.mjs";
+import { resolveFilteringSearchParams } from "@tulip-systems/query";
+//#region src/root/lib/search-params.ts
+const localDriveTreeFilterSearchParams = resolveFilteringSearchParams(localDriveFilters);
+//#endregion
+export { localDriveTreeFilterSearchParams };

package/dist/root/lib/service.server.d.mts

@@ -0,0 +1,522 @@
+import { CreateLocalDriveFolderSchema, GetLocalDriveNodesByParentIdInput, GetLocalFileURLSchema, ListLocalDriveFlatSchema, ListLocalDriveTreeSchema, LocalDriveFileNode, LocalDriveNode, LocalDriveNodeChild, LocalDriveNodeWithAsset, LocalDriveNodeWithChildren, LocalNode, PresignLocalDriveFileInput, UpdateLocalDriveNodeInput, UploadLocalDriveFileSchema } from "./validators.mjs";
+import { LocalDriveDatabaseProvider } from "./database/contracts.mjs";
+import { DriveAdapterTypes, DriveArchive, DriveDirectUpload, DriveNodeMutations, DriveNodeQueries, DriveNodeReader, DrivePresignedUpload, DrivePreviewGenerator, DriveReadonly } from "@tulip-systems/drive";
+import { OffsetPaginatedResponse } from "@tulip-systems/query";
+import { ObjectBodyInput } from "@tulip-systems/storage";
+import { Storage } from "@tulip-systems/storage/server";
+//#region src/root/lib/service.server.d.ts
+/**
+ * Drive Service Config
+ */
+type LocalDriveConfig = {
+  database: LocalDriveDatabaseProvider;
+  storage: Storage;
+};
+type LocalDriveTypes = DriveAdapterTypes<LocalDriveNode, {
+  createFolderInput: CreateLocalDriveFolderSchema;
+  getNodesByParentIdInput: GetLocalDriveNodesByParentIdInput;
+  listTreeInput: ListLocalDriveTreeSchema;
+  listTreeNode: LocalDriveNodeWithAsset;
+  nodeChild: LocalDriveNodeChild;
+  nodeWithChildren: LocalDriveNodeWithChildren;
+  presignUploadInput: PresignLocalDriveFileInput;
+  presignUploadNode: LocalDriveFileNode;
+  updateNodeInput: UpdateLocalDriveNodeInput;
+  uploadBody: ObjectBodyInput;
+  uploadFileInput: UploadLocalDriveFileSchema;
+}>;
+/**
+ * Drive Service
+ */
+declare class LocalDrive implements DriveNodeReader<LocalDriveTypes>, DriveNodeQueries<LocalDriveTypes>, DriveNodeMutations<LocalDriveTypes>, DriveDirectUpload<LocalDriveTypes>, DrivePresignedUpload<LocalDriveTypes>, DrivePreviewGenerator, DriveReadonly<LocalDriveTypes>, DriveArchive<LocalDriveTypes> {
+  #private;
+  storage: Storage;
+  constructor({ database, storage }: LocalDriveConfig);
+  /**
+   * Retrieves the node row for a given id.
+   *
+   * This is a thin lookup helper that returns the raw database result for the
+   * matching node. It does not load children, variants, or perform namespace
+   * validation.
+   *
+   * @param id - The node identifier.
+   * @returns A promise resolving to the matching node row as a single-item array,
+   * or an empty array when no node exists.
+   */
+  getNodeById(id: string): Promise<LocalDriveNode | null>;
+  /**
+   * Retrieves a node together with its direct children for a namespace.
+   *
+   * This is used by the drive UI when opening a node detail view that expects
+   * the immediate child this.#nodes in the same payload.
+   *
+   * @param input - The target node id and namespace.
+   * @returns The node with its children when found, otherwise `null`.
+   */
+  getNodeWithChildren(input: {
+    id: string;
+    namespace: string;
+  }): Promise<LocalDriveNodeWithChildren | null>;
+  /**
+   * Lists this.#nodes within a folder scope using the current table-query filters.
+   *
+   * Behavior:
+   * - Scopes results to a namespace
+   * - Resolves either root this.#nodes (`parentId = null`) or a specific parent folder
+   * - Applies optional filters such as ids, types, hidden state, and archive state
+   * - Applies search and sorting through the shared table-query utilities
+   *
+   * @param input - Table query input containing drive filters, search, and sorting.
+   * @returns A promise resolving to the matching child this.#nodes.
+   */
+  getNodesByParentId(input: GetLocalDriveNodesByParentIdInput): Promise<LocalDriveNode[]>;
+  /**
+   * Lists tree-scoped this.#nodes with pagination, search, and richer local filters.
+   *
+   * This query is intended for admin table views where additional local fields
+   * such as subtype and contentType are part of the filtering contract.
+   *
+   * @param input - Table query input with tree filters.
+   * @returns A paginated table-query response.
+   */
+  listTree({ filters, ...query }: ListLocalDriveTreeSchema): Promise<OffsetPaginatedResponse<LocalDriveNodeWithAsset>>;
+  /**
+   * Lists flat this.#nodes with pagination, search, and richer local filters.
+   *
+   * Unlike `listTree`, this query ignores parent scoping and is intended for
+   * flat file-manager style views.
+   *
+   * @param input - Table query input with flat filters.
+   * @returns A paginated table-query response.
+   */
+  listFlat({ filters, ...query }: ListLocalDriveFlatSchema): Promise<OffsetPaginatedResponse<LocalDriveNodeWithAsset>>;
+  /**
+   * Resolves the ancestor chain for a folder or file node.
+   *
+   * The returned list starts with the root-most ancestor and ends with the
+   * requested node. This is primarily used for breadcrumb navigation.
+   *
+   * @param input - The node id and namespace to resolve.
+   * @returns A promise resolving to the ordered ancestor chain.
+   */
+  getFolderParents(input: {
+    id: string | null;
+    namespace: string;
+  }): Promise<{
+    depth: number;
+    name: string;
+    id: string;
+    parentId: string | null;
+  }[]>;
+  /**
+   * Retrieves the structural subtree for one or more root node ids.
+   *
+   * The result includes the provided start this.#nodes and all descendant this.#nodes,
+   * returned as a lightweight shape containing only the fields needed for
+   * recursive drive operations such as delete, archive, and validation.
+   *
+   * Depth starts at `0` for the provided root this.#nodes and increases for each
+   * descendant level. Duplicate paths are collapsed by keeping the minimum depth.
+   *
+   * @param ids - Root node ids to traverse from.
+   * @returns A promise resolving to the subtree rows for the provided this.#nodes.
+   */
+  getNodeChildren(ids: string[]): Promise<{
+    depth: number;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    type: "folder" | "file";
+    subtype: "image" | "document" | "spreadsheet" | "video" | "audio" | "archive" | "other";
+    size: number | null;
+    contentType: string | null;
+    readonly: boolean;
+    hidden: boolean;
+    archivedAt: Date | null;
+    parentId: string | null;
+    links: {
+      view: string | null;
+      download: string | null;
+      preview: string | null;
+      thumbnail: string | null;
+    };
+    availability: "pending" | "ready" | "failed";
+    provider: "local";
+    assetId: string | null;
+  }[]>;
+  /**
+   * Resolves an access URL for a file node and the requested variant.
+   *
+   * Behavior:
+   * - Rejects folder this.#nodes because only file this.#nodes can resolve a file URL
+   * - Reuses a cached URL when an unexpired entry exists for the requested
+   *   variant and disposition
+   * - Resolves the requested preview variant asset when available
+   * - Falls back to the main file asset when the requested variant does not exist
+   * - Delegates final URL generation to the storage service
+   * - Stores the generated URL in the local cache table for future reuse
+   *
+   * @param node - The file node to resolve.
+   * @param options - URL options such as variant and content disposition.
+   * @returns A promise resolving to a temporary file URL.
+   */
+  getURL(node: LocalNode, options?: GetLocalFileURLSchema): Promise<string>;
+  /**
+   * Moves a node to a different parent folder.
+   *
+   * The target parent is validated before the move is persisted. Moving a node
+   * into itself or into one of its descendants is rejected to keep the tree
+   * structure valid.
+   *
+   * @param input - The node id and the target parent id.
+   * @returns A promise resolving to the updated node.
+   * @throws {ORPCError} If the move is invalid.
+   */
+  moveNode(input: {
+    id: string;
+    parentId: string | null;
+  }): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    type: "folder" | "file";
+    subtype: "image" | "document" | "spreadsheet" | "video" | "audio" | "archive" | "other";
+    size: number | null;
+    contentType: string | null;
+    readonly: boolean;
+    hidden: boolean;
+    archivedAt: Date | null;
+    parentId: string | null;
+    links: {
+      view: string | null;
+      download: string | null;
+      preview: string | null;
+      thumbnail: string | null;
+    };
+    availability: "pending" | "ready" | "failed";
+    provider: "local";
+    assetId: string | null;
+  }>;
+  /**
+   * Uploads a file through the storage service and creates the matching node.
+   *
+   * Behavior:
+   * - Validates the parent folder when `parentId` is provided
+   * - Uploads the file bytes through the storage service
+   * - Persists the created storage asset id on the node
+   * - Cleans up the uploaded asset when node creation fails
+   *
+   * @param input - File metadata and body.
+   * @returns A promise resolving to the created file node.
+   * @throws {ORPCError} If validation or persistence fails.
+   */
+  uploadFile(input: UploadLocalDriveFileSchema & {
+    body: ObjectBodyInput;
+  }): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    type: "folder" | "file";
+    subtype: "image" | "document" | "spreadsheet" | "video" | "audio" | "archive" | "other";
+    size: number | null;
+    contentType: string | null;
+    readonly: boolean;
+    hidden: boolean;
+    archivedAt: Date | null;
+    parentId: string | null;
+    links: {
+      view: string | null;
+      download: string | null;
+      preview: string | null;
+      thumbnail: string | null;
+    };
+    availability: "pending" | "ready" | "failed";
+    provider: "local";
+    assetId: string | null;
+  }>;
+  /**
+   * Creates a direct upload intent and the matching file node.
+   *
+   * Behavior:
+   * - Validates the parent folder when `parentId` is provided
+   * - Requests a presigned upload from the storage service
+   * - Creates the file node linked to the pending storage asset
+   * - Purges the pending asset when node creation fails
+   *
+   * @param input - File metadata used to create the upload intent.
+   * @returns The created asset intent, presigned URL, and file node.
+   * @throws {ORPCError} If validation or node creation fails.
+   */
+  presignUpload(input: PresignLocalDriveFileInput): Promise<{
+    uploadId: string;
+    presignedUrl: string;
+    node: LocalDriveFileNode;
+    asset: {
+      id: string;
+      createdAt: Date;
+      updatedAt: Date;
+      provider: "s3";
+      bucket: string;
+      key: string;
+      status: "pending" | "ready" | "error";
+      visibility: "private" | "public";
+      size: number | null;
+      contentType: string | null;
+      uploadId: string;
+      name: string | null;
+      metadata: Record<string, unknown> | null;
+      etag: string | null;
+      uploadedAt: Date;
+      deletedAt: Date | null;
+    };
+  }>;
+  /**
+   * Finalizes a presigned upload and synchronizes the node metadata.
+   *
+   * Behavior:
+   * - Confirms the pending asset through the storage service
+   * - Finds the matching node by `assetId`
+   * - Synchronizes final asset metadata onto the node
+   * - Schedules preview generation for image files
+   *
+   * @param uploadId - The storage upload id returned by the presign step.
+   * @returns A promise resolving to the finalized file node.
+   * @throws {ORPCError} If the asset or node cannot be resolved.
+   */
+  confirmUpload(uploadId: string): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    subtype: "image" | "document" | "spreadsheet" | "video" | "audio" | "archive" | "other";
+    size: number | null;
+    contentType: string | null;
+    readonly: boolean;
+    hidden: boolean;
+    archivedAt: Date | null;
+    parentId: string | null;
+    links: {
+      view: string | null;
+      download: string | null;
+      preview: string | null;
+      thumbnail: string | null;
+    };
+    availability: "pending" | "ready" | "failed";
+    provider: "local";
+    assetId: string | null;
+    type: "file";
+  }>;
+  /**
+   * Generates preview assets for an image node.
+   *
+   * The original file is loaded from storage, resized to the configured device
+   * widths, uploaded as separate storage assets, and linked through
+   * `node_variants`. Existing preview variants are skipped.
+   *
+   * @param input - The target file node identifier.
+   * @returns A promise that resolves once preview generation completes.
+   * @throws {ORPCError} If the source node or asset cannot be resolved.
+   */
+  generatePreviews(input: {
+    id: string;
+  }): Promise<void>;
+  /**
+   * Creates a folder node in the drive tree.
+   *
+   * The parent folder is validated before the folder is inserted. Folders do
+   * not own a storage asset and are stored purely as drive metadata.
+   *
+   * @param input - Folder metadata.
+   * @returns A promise resolving to the created folder node.
+   * @throws {ORPCError} If validation or insertion fails.
+   */
+  createFolder(input: CreateLocalDriveFolderSchema): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    type: "folder" | "file";
+    subtype: "image" | "document" | "spreadsheet" | "video" | "audio" | "archive" | "other";
+    size: number | null;
+    contentType: string | null;
+    readonly: boolean;
+    hidden: boolean;
+    archivedAt: Date | null;
+    parentId: string | null;
+    links: {
+      view: string | null;
+      download: string | null;
+      preview: string | null;
+      thumbnail: string | null;
+    };
+    availability: "pending" | "ready" | "failed";
+    provider: "local";
+    assetId: string | null;
+  }>;
+  /**
+   * Updates mutable node metadata.
+   *
+   * Supported updates currently include renaming, reparenting, visibility flags,
+   * and archive state. Structural updates are validated before being persisted.
+   *
+   * @param id - The target node id.
+   * @param data - Partial node fields to update.
+   * @returns A promise resolving to the updated node.
+   * @throws {ORPCError} If the node does not exist or the update is invalid.
+   */
+  updateNode(id: string, data: UpdateLocalDriveNodeInput): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    type: "folder" | "file";
+    subtype: "image" | "document" | "spreadsheet" | "video" | "audio" | "archive" | "other";
+    size: number | null;
+    contentType: string | null;
+    readonly: boolean;
+    hidden: boolean;
+    archivedAt: Date | null;
+    parentId: string | null;
+    links: {
+      view: string | null;
+      download: string | null;
+      preview: string | null;
+      thumbnail: string | null;
+    };
+    availability: "pending" | "ready" | "failed";
+    provider: "local";
+    assetId: string | null;
+  }>;
+  /**
+   * Sets the readonly state for multiple this.#nodes.
+   *
+   * This method is intended for bulk lock and unlock operations in the drive UI.
+   *
+   * @param ids - The node ids to update.
+   * @param readonly - The readonly state to apply.
+   * @returns A promise resolving to the updated this.#nodes.
+   * @throws {ORPCError} If no ids are provided or no matching this.#nodes are found.
+   */
+  setReadonly(ids: string[], readonly: boolean): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    type: "folder" | "file";
+    subtype: "image" | "document" | "spreadsheet" | "video" | "audio" | "archive" | "other";
+    size: number | null;
+    contentType: string | null;
+    readonly: boolean;
+    hidden: boolean;
+    archivedAt: Date | null;
+    parentId: string | null;
+    links: {
+      view: string | null;
+      download: string | null;
+      preview: string | null;
+      thumbnail: string | null;
+    };
+    availability: "pending" | "ready" | "failed";
+    provider: "local";
+    assetId: string | null;
+  }[]>;
+  /**
+   * Archives this.#nodes by setting their archive timestamp.
+   *
+   * This is a drive-level archive state and does not delete the underlying
+   * storage assets.
+   *
+   * @param ids - The node ids to archive.
+   * @returns A promise resolving to the archived this.#nodes.
+   * @throws {ORPCError} If no ids are provided or no matching this.#nodes are found.
+   */
+  archiveNodes(ids: string[]): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    type: "folder" | "file";
+    subtype: "image" | "document" | "spreadsheet" | "video" | "audio" | "archive" | "other";
+    size: number | null;
+    contentType: string | null;
+    readonly: boolean;
+    hidden: boolean;
+    archivedAt: Date | null;
+    parentId: string | null;
+    links: {
+      view: string | null;
+      download: string | null;
+      preview: string | null;
+      thumbnail: string | null;
+    };
+    availability: "pending" | "ready" | "failed";
+    provider: "local";
+    assetId: string | null;
+  }[]>;
+  /**
+   * Restores archived this.#nodes by clearing their archive timestamp.
+   *
+   * @param ids - The node ids to restore.
+   * @returns A promise resolving to the restored this.#nodes.
+   * @throws {ORPCError} If no ids are provided or no matching this.#nodes are found.
+   */
+  restoreNodes(ids: string[]): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    type: "folder" | "file";
+    subtype: "image" | "document" | "spreadsheet" | "video" | "audio" | "archive" | "other";
+    size: number | null;
+    contentType: string | null;
+    readonly: boolean;
+    hidden: boolean;
+    archivedAt: Date | null;
+    parentId: string | null;
+    links: {
+      view: string | null;
+      download: string | null;
+      preview: string | null;
+      thumbnail: string | null;
+    };
+    availability: "pending" | "ready" | "failed";
+    provider: "local";
+    assetId: string | null;
+  }[]>;
+  /**
+   * Permanently deletes a node subtree and all linked assets.
+   *
+   * The subtree includes the provided node and all descendants. Associated file
+   * assets and generated preview assets are purged from storage after the this.#nodes
+   * are removed from the drive catalog.
+   *
+   * @param id - The root node id to delete.
+   * @throws {ORPCError} If the node does not exist.
+   */
+  deleteNode(id: string): Promise<void>;
+  /**
+   * Permanently deletes multiple node subtrees and their linked assets.
+   *
+   * Each provided id is treated as a subtree root. All descendant this.#nodes are
+   * removed together with their main file assets and generated preview assets.
+   *
+   * @param ids - Root node ids to delete.
+   * @returns A promise that resolves when deletion completes.
+   * @throws {ORPCError} If no ids are provided or no matching this.#nodes are found.
+   */
+  deleteNodes(ids: string[]): Promise<void>;
+}
+//#endregion
+export { LocalDrive, LocalDriveConfig };