@tulip-systems/drive 0.8.1 → 0.8.3

package/dist/providers/local/lib/schema.mjs

@@ -0,0 +1,70 @@
+import { imageVariants, nodeSubtypes } from "./constants.mjs";
+import { baseColumns } from "@tulip-systems/core/config";
+import { imageDispositions, storageAssets } from "@tulip-systems/core/storage";
+import { relations } from "drizzle-orm";
+import { boolean, pgEnum, pgTable, unique } from "drizzle-orm/pg-core";
+
+//#region src/providers/local/lib/schema.ts
+const nodeTypeEnum = pgEnum("node_types", ["file", "folder"]);
+/**
+* Node table
+*/
+const nodes = pgTable("nodes", (t) => ({
+	...baseColumns,
+	name: t.text().notNull(),
+	namespace: t.text().notNull().default("global"),
+	type: nodeTypeEnum(),
+	subtype: t.text({ enum: nodeSubtypes }).notNull().default("other"),
+	size: t.integer(),
+	contentType: t.varchar({ length: 255 }),
+	readonly: boolean().default(false),
+	hidden: boolean().default(false),
+	archivedAt: t.timestamp(),
+	parentId: t.uuid().references(() => nodes.id, { onDelete: "cascade" }),
+	assetId: t.uuid().references(() => storageAssets.id, { onDelete: "cascade" })
+}));
+const nodesRelations = relations(nodes, ({ one, many }) => ({
+	parent: one(nodes, {
+		fields: [nodes.parentId],
+		references: [nodes.id],
+		relationName: "parent"
+	}),
+	children: many(nodes, { relationName: "parent" }),
+	urls: many(nodePresignedUrls),
+	variants: many(nodeVariants)
+}));
+/**
+* Node variants table
+*/
+const nodeVariants = pgTable("node_variants", (t) => ({
+	...baseColumns,
+	nodeId: t.uuid().notNull().references(() => nodes.id, { onDelete: "cascade" }),
+	assetId: t.uuid().notNull().references(() => storageAssets.id, { onDelete: "cascade" }),
+	variant: t.text({ enum: imageVariants }).notNull(),
+	width: t.integer().notNull()
+}));
+const nodeVariantsRelations = relations(nodeVariants, ({ one }) => ({ node: one(nodes, {
+	fields: [nodeVariants.nodeId],
+	references: [nodes.id],
+	relationName: "node"
+}) }));
+/**
+* Node presigned urls table
+*/
+const nodePresignedUrls = pgTable("node_presigned_urls", (t) => ({
+	...baseColumns,
+	url: t.text().notNull().unique(),
+	variant: t.text({ enum: imageVariants }).notNull(),
+	disposition: t.text({ enum: imageDispositions }).notNull(),
+	expiresAt: t.timestamp().notNull(),
+	nodeId: t.uuid().notNull().references(() => nodes.id, { onDelete: "cascade" }),
+	variantId: t.uuid().references(() => nodeVariants.id, { onDelete: "set null" })
+}), (t) => [unique("node_presigned_url_unique").on(t.nodeId, t.variant, t.disposition)]);
+const nodePresignedUrlsRelations = relations(nodePresignedUrls, ({ one }) => ({ node: one(nodes, {
+	fields: [nodePresignedUrls.nodeId],
+	references: [nodes.id],
+	relationName: "node"
+}) }));
+
+//#endregion
+export { nodePresignedUrls, nodePresignedUrlsRelations, nodeTypeEnum, nodeVariants, nodeVariantsRelations, nodes, nodesRelations };

package/dist/providers/local/lib/search-params.d.mts

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

package/dist/providers/local/lib/search-params.mjs

@@ -0,0 +1,8 @@
+import { localDriveFilters } from "../config/filters.mjs";
+import { resolveFiltersSearchParams } from "@tulip-systems/core/data-tables";
+
+//#region src/providers/local/lib/search-params.ts
+const localDriveTreeFilterSearchParams = resolveFiltersSearchParams(localDriveFilters);
+
+//#endregion
+export { localDriveTreeFilterSearchParams };

package/dist/providers/local/lib/service.server.d.mts

@@ -0,0 +1,488 @@
+import { DriveArchive, DriveDirectUpload, DriveNodeMutations, DrivePresignedUpload, DrivePreviewGenerator, DriveReader, DriveReadonly } from "../../../lib/contracts.mjs";
+import { CreateLocalDriveFolderSchema, GetLocalDriveNodesByParentIdInput, GetLocalFileURLSchema, ListLocalDriveFlatSchema, ListLocalDriveTreeSchema, LocalDriveFileNode, LocalDriveNode, LocalDriveNodeChild, LocalDriveNodeWithAsset, LocalDriveNodeWithChildren, LocalNode, PresignLocalDriveFileInput, UpdateLocalDriveNodeInput, UploadLocalDriveFileSchema } from "./validators.mjs";
+import { TDatabaseSchema } from "@tulip-systems/core/config";
+import { ObjectBodyInput } from "@tulip-systems/core/storage";
+import { TableQueryResponse } from "@tulip-systems/core/data-tables/server";
+import { Database } from "@tulip-systems/core/database/server";
+import { Storage } from "@tulip-systems/core/storage/server";
+
+//#region src/providers/local/lib/service.server.d.ts
+/**
+ * Drive Service Config
+ */
+type LocalDriveConfig<TSchema extends TDatabaseSchema> = {
+  db: Database<TSchema>;
+  storage: Storage<TSchema>;
+};
+/**
+ * Drive Service
+ */
+declare class LocalDrive<TSchema extends TDatabaseSchema> implements DriveReader<LocalDriveNode>, DriveNodeMutations<LocalDriveNode>, DriveDirectUpload<LocalDriveNode, ObjectBodyInput>, DrivePresignedUpload<LocalDriveFileNode>, DrivePreviewGenerator, DriveReadonly<LocalDriveNode>, DriveArchive<LocalDriveNode> {
+  #private;
+  storage: Storage<TSchema>;
+  constructor({
+    db,
+    storage
+  }: LocalDriveConfig<TSchema>);
+  /**
+   * 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 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 nodes within a folder scope using the current table-query filters.
+   *
+   * Behavior:
+   * - Scopes results to a namespace
+   * - Resolves either root 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 nodes.
+   */
+  getNodesByParentId({
+    filters,
+    ...query
+  }: GetLocalDriveNodesByParentIdInput): Promise<LocalDriveNode[]>;
+  /**
+   * Lists tree-scoped 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<TableQueryResponse<LocalDriveNodeWithAsset>>;
+  /**
+   * Lists flat 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<TableQueryResponse<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<(Pick<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    type: "file" | "folder" | null;
+    readonly: boolean | null;
+    size: number | null;
+    contentType: string | null;
+    namespace: string;
+    subtype: "image" | "document" | "spreadsheet" | "video" | "audio" | "archive" | "other";
+    hidden: boolean | null;
+    archivedAt: Date | null;
+    parentId: string | null;
+    assetId: string | null;
+  }, "id" | "name" | "parentId"> & {
+    depth: number;
+  })[]>;
+  /**
+   * Retrieves the structural subtree for one or more root node ids.
+   *
+   * The result includes the provided start nodes and all descendant 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 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 nodes.
+   */
+  getNodeChildren(ids: string[]): Promise<LocalDriveNodeChild[]>;
+  /**
+   * Resolves an access URL for a file node and the requested variant.
+   *
+   * Behavior:
+   * - Rejects folder nodes because only file 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 {ServerError} If the move is invalid.
+   */
+  moveNode(input: {
+    id: string;
+    parentId: string | null;
+  }): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    type: "file" | "folder";
+    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: "ready" | "pending" | "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 {ServerError} If validation or persistence fails.
+   */
+  uploadFile(input: UploadLocalDriveFileSchema & {
+    body: ObjectBodyInput;
+  }): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    type: "file" | "folder";
+    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: "ready" | "pending" | "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 {ServerError} If validation or node creation fails.
+   */
+  presignUpload(input: PresignLocalDriveFileInput): Promise<{
+    uploadId: string;
+    presignedUrl: string;
+    node: LocalDriveFileNode;
+    asset: {
+      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;
+    };
+  }>;
+  /**
+   * 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 {ServerError} If the asset or node cannot be resolved.
+   */
+  confirmUpload(uploadId: string): Promise<LocalDriveFileNode>;
+  /**
+   * 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 {ServerError} 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 {ServerError} If validation or insertion fails.
+   */
+  createFolder(input: CreateLocalDriveFolderSchema): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    type: "file" | "folder";
+    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: "ready" | "pending" | "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 {ServerError} 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: "file" | "folder";
+    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: "ready" | "pending" | "failed";
+    provider: "local";
+    assetId: string | null;
+  }>;
+  /**
+   * Sets the readonly state for multiple 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 nodes.
+   * @throws {ServerError} If no ids are provided or no matching nodes are found.
+   */
+  setReadonly(ids: string[], readonly: boolean): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    type: "file" | "folder";
+    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: "ready" | "pending" | "failed";
+    provider: "local";
+    assetId: string | null;
+  }[]>;
+  /**
+   * Archives 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 nodes.
+   * @throws {ServerError} If no ids are provided or no matching nodes are found.
+   */
+  archiveNodes(ids: string[]): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    type: "file" | "folder";
+    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: "ready" | "pending" | "failed";
+    provider: "local";
+    assetId: string | null;
+  }[]>;
+  /**
+   * Restores archived nodes by clearing their archive timestamp.
+   *
+   * @param ids - The node ids to restore.
+   * @returns A promise resolving to the restored nodes.
+   * @throws {ServerError} If no ids are provided or no matching nodes are found.
+   */
+  restoreNodes(ids: string[]): Promise<{
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    namespace: string;
+    type: "file" | "folder";
+    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: "ready" | "pending" | "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 nodes
+   * are removed from the drive catalog.
+   *
+   * @param id - The root node id to delete.
+   * @throws {ServerError} 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 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 {ServerError} If no ids are provided or no matching nodes are found.
+   */
+  deleteNodes(ids: string[]): Promise<void>;
+}
+//#endregion
+export { LocalDrive, LocalDriveConfig };