@tulip-systems/drive 0.8.0 → 0.8.2

package/dist/providers/google/lib/service.server.mjs

@@ -0,0 +1,613 @@
+import { GOOGLE_DRIVE_FOLDER_MIME_TYPE, GOOGLE_DRIVE_NODE_FIELDS } from "./constants.mjs";
+import { GoogleDriveNodeDTO } from "./dto.mjs";
+import { escapeGoogleDriveQueryValue, isGoogleNotFound, toGoogleDriveReadable } from "./helpers.mjs";
+import { ServerError } from "@tulip-systems/core/router/server";
+import { google } from "googleapis";
+
+//#region src/providers/google/lib/service.server.ts
+const DEFAULT_PAGE_SIZE = 10;
+const CHILDREN_PAGE_SIZE = 1e3;
+/**
+* Google Drive provider.
+*
+* A single service instance can operate on multiple Google shared drives. The
+* shared Drive `namespace` is the Google `driveId`, so namespace is supplied by
+* method inputs rather than by the constructor.
+*/
+var GoogleDrive = class {
+	client;
+	constructor(config) {
+		this.client = google.drive({
+			auth: config.auth,
+			version: "v3"
+		});
+	}
+	/**
+	* Fetches raw Google Drive metadata for a file or folder.
+	*
+	* Google Drive uses the same `files.get` endpoint for files and folders. We
+	* request only `GOOGLE_DRIVE_NODE_FIELDS` so DTO mapping receives a predictable
+	* shape and we avoid over-fetching provider metadata.
+	*
+	* A Google 404 is translated to `null` to match the public `getNodeById`
+	* contract. All other errors are rethrown because they represent real failures
+	* such as insufficient permissions, invalid credentials, quota limits, or API
+	* outages.
+	*/
+	async #getFile(id) {
+		try {
+			return (await this.client.files.get({
+				fileId: id,
+				supportsAllDrives: true,
+				fields: GOOGLE_DRIVE_NODE_FIELDS
+			})).data;
+		} catch (error) {
+			if (isGoogleNotFound(error)) return null;
+			throw error;
+		}
+	}
+	/**
+	* Loads a single Google Drive file/folder by its Google file id.
+	*
+	* Returns `null` when Google reports the file does not exist or is not visible to
+	* the authenticated account. Other Google API errors are allowed to bubble up so
+	* callers do not accidentally treat permission, quota, or transport failures as
+	* missing data.
+	*
+	* The returned Google metadata is normalized into the shared Drive node shape by
+	* `#toNode`, which also validates that Google returned the minimum metadata we
+	* need to identify the node and its namespace.
+	*/
+	async getNodeById(id) {
+		const file = await this.#getFile(id);
+		return file ? this.#toNode(file) : null;
+	}
+	/**
+	* Converts a table sort field into a Google Drive `orderBy` value.
+	*
+	* Google Drive only accepts a fixed set of field names in `files.list.orderBy`.
+	* The table layer uses provider-neutral names such as `createdAt` and
+	* `updatedAt`, so this method maps those aliases to Google's native field names.
+	*
+	* Unknown sort fields intentionally fall back to `modifiedTime desc` instead of
+	* being passed through, because Google returns a 400 for unsupported order fields.
+	*/
+	#orderBy(input) {
+		const direction = input.order === "asc" ? "" : " desc";
+		switch (input.sort) {
+			case "name": return `name${direction}`;
+			case "createdAt":
+			case "createdTime": return `createdTime${direction}`;
+			case "updatedAt":
+			case "modifiedTime": return `modifiedTime${direction}`;
+			default: return "modifiedTime desc";
+		}
+	}
+	/**
+	* Scopes results to a parent folder.
+	*
+	* Google Drive represents folder membership as `'<folderId>' in parents`.
+	* A `null` parent maps to the provider namespace/root drive id.
+	* An `undefined` parent means no parent filter should be applied.
+	*/
+	#parentQuery(input) {
+		if (input.parentId === void 0) return null;
+		return `'${escapeGoogleDriveQueryValue(input.parentId ?? input.namespace)}' in parents`;
+	}
+	/**
+	* Filters results to a specific set of Google file ids.
+	*/
+	#idQuery(nodeIds) {
+		if (!nodeIds?.length) return null;
+		return `(${nodeIds.map((id) => `id = '${escapeGoogleDriveQueryValue(id)}'`).join(" or ")})`;
+	}
+	/**
+	* Converts provider-neutral node types to Google Drive MIME-type filters.
+	*
+	* Google Drive folders are identified by their folder MIME type. Every other
+	* MIME type is treated as a file.
+	*/
+	#typeQuery(types) {
+		if (types?.length !== 1) return null;
+		return types[0] === "folder" ? `mimeType = '${GOOGLE_DRIVE_FOLDER_MIME_TYPE}'` : `mimeType != '${GOOGLE_DRIVE_FOLDER_MIME_TYPE}'`;
+	}
+	/**
+	* Filters files by MIME type.
+	*
+	* This only applies to files. Folder filtering should use `#typeQuery`.
+	*/
+	#contentTypeQuery(contentTypes) {
+		if (!contentTypes?.length) return null;
+		return `(${contentTypes.map((contentType) => `mimeType = '${escapeGoogleDriveQueryValue(contentType)}'`).join(" or ")})`;
+	}
+	/**
+	* Filters archived/active nodes.
+	*
+	* Google Drive calls this state `trashed`; the shared Drive contract calls it
+	* archived/soft-deleted. By default we return active nodes only.
+	*/
+	#archiveQuery(isArchived) {
+		return `trashed = ${isArchived === true ? "true" : "false"}`;
+	}
+	/**
+	* Applies a name search.
+	*
+	* Google Drive supports `name contains '<value>'`, which is a substring match.
+	*/
+	#searchQuery(search) {
+		if (!search) return null;
+		return `name contains '${escapeGoogleDriveQueryValue(search)}'`;
+	}
+	#buildQuery(input) {
+		return [
+			this.#parentQuery(input),
+			this.#idQuery(input.nodeIds),
+			this.#typeQuery(input.types),
+			this.#contentTypeQuery(input.contentTypes),
+			this.#archiveQuery(input.isArchived),
+			this.#searchQuery(input.search)
+		].filter((clause) => typeof clause === "string" && clause.length > 0).join(" and ");
+	}
+	/**
+	* Lists the direct children of a Google Drive folder.
+	*
+	* Google Drive stores both files and folders behind the `files.list` endpoint.
+	* This helper translates our drive query input into a Google Drive search query
+	* and returns only the immediate children for the requested parent.
+	*
+	* The result is paginated by Google, so we keep requesting pages until all
+	* matching children are loaded. Recursive traversal is intentionally not handled
+	* here; callers that need full subtrees should use `getNodeChildren`.
+	*/
+	async #listChildren(input) {
+		const filters = input?.filters;
+		const files = [];
+		let pageToken;
+		do {
+			const result = await this.client.files.list({
+				pageToken,
+				pageSize: CHILDREN_PAGE_SIZE,
+				corpora: "drive",
+				driveId: input.filters.namespace,
+				includeItemsFromAllDrives: true,
+				supportsAllDrives: true,
+				q: this.#buildQuery({
+					namespace: input.filters.namespace,
+					parentId: input.filters.parentId,
+					nodeIds: filters?.nodeIds,
+					types: filters?.types,
+					contentTypes: filters?.contentTypes,
+					isArchived: filters?.isArchived,
+					search: input?.search
+				}),
+				orderBy: this.#orderBy(input),
+				fields: `nextPageToken, files(${GOOGLE_DRIVE_NODE_FIELDS})`
+			});
+			files.push(...result.data.files ?? []);
+			pageToken = result.data.nextPageToken ?? void 0;
+		} while (pageToken);
+		return files.map((file) => this.#toNode(file));
+	}
+	/**
+	* Loads a node and its direct children within a namespace.
+	*
+	* Google Drive does not enforce our provider-neutral `namespace` at `files.get`
+	* time, so the node is fetched by id first and then checked against the requested
+	* namespace/shared drive. A missing node or namespace mismatch returns
+	* `null`, matching the shared Drive reader contract.
+	*
+	* Only direct children are loaded. Recursive traversal is handled separately by
+	* `getNodeChildren`.
+	*/
+	async getNodeWithChildren(input) {
+		const node = await this.getNodeById(input.id);
+		if (!node || node.namespace !== input.namespace) return null;
+		const children = await this.#listChildren({ filters: {
+			parentId: node.id,
+			namespace: node.namespace,
+			isArchived: false
+		} });
+		return {
+			...node,
+			children
+		};
+	}
+	/**
+	* Lists the direct children of a parent folder.
+	*
+	* This is the Google Drive implementation of the shared Drive reader method. It
+	* delegates to `#listChildren`, which translates the provider-neutral filters,
+	* search, and sorting options into a Google Drive `files.list` query.
+	*
+	* Only immediate children are returned. Recursive traversal is handled by
+	* `getNodeChildren`.
+	*/
+	async getNodesByParentId(input) {
+		return this.#listChildren(input);
+	}
+	/**
+	* Resolves the Google Drive page token for a numeric table cursor.
+	*
+	* The shared table API uses numeric cursors (`0`, `1`, `2`, ...), while Google
+	* Drive pagination uses opaque `nextPageToken` values. To bridge that mismatch,
+	* we walk Google pages until we reach the requested table page.
+	*
+	* The intermediate requests only fetch file ids because their content is thrown
+	* away; we only need each response's `nextPageToken`.
+	*
+	* Returns `exhausted: true` when Google runs out of pages before the requested
+	* cursor is reached.
+	*/
+	async #pageCursorAt(input, remainingPages, pageToken) {
+		if (remainingPages === 0) return {
+			pageToken,
+			exhausted: false
+		};
+		const nextPageToken = (await this.client.files.list({
+			pageSize: input.limit,
+			pageToken,
+			corpora: "drive",
+			driveId: input.namespace,
+			includeItemsFromAllDrives: true,
+			supportsAllDrives: true,
+			q: input.q,
+			orderBy: input.orderBy,
+			fields: "nextPageToken, files(id)"
+		})).data.nextPageToken ?? void 0;
+		if (!nextPageToken) return { exhausted: true };
+		return this.#pageCursorAt(input, remainingPages - 1, nextPageToken);
+	}
+	/**
+	* Lists Google Drive nodes using the shared table pagination shape.
+	*
+	* The shared table API uses numeric cursors, but Google Drive uses opaque page
+	* tokens. Before fetching the requested page, `#pageCursorAt` advances through
+	* Google pages until it resolves the page token for the requested numeric cursor.
+	*
+	* Google Drive does not return a total row count for `files.list`, so pagination
+	* totals are estimated from the current cursor, returned page size, and whether
+	* Google reports another page. The estimate is only meant to support table/infinite
+	* pagination controls; it should not be treated as an exact item count.
+	*/
+	async #listNodes(input) {
+		const limit = input.limit ?? DEFAULT_PAGE_SIZE;
+		const cursor = input.cursor ?? 0;
+		const pageCursor = await this.#pageCursorAt({
+			...input,
+			limit
+		}, cursor);
+		if (pageCursor.exhausted) return {
+			data: [],
+			pagination: {
+				total: cursor * limit,
+				totalPages: Math.max(1, cursor),
+				limit,
+				hasNextPage: false,
+				hasPreviousPage: cursor > 0,
+				cursor,
+				nextCursor: null,
+				previousCursor: cursor > 0 ? cursor - 1 : null
+			}
+		};
+		const result = await this.client.files.list({
+			pageSize: limit,
+			pageToken: pageCursor.pageToken,
+			corpora: "drive",
+			driveId: input.namespace,
+			includeItemsFromAllDrives: true,
+			supportsAllDrives: true,
+			q: input.q,
+			orderBy: input.orderBy,
+			fields: `nextPageToken, files(${GOOGLE_DRIVE_NODE_FIELDS})`
+		});
+		const data = result.data.files?.map((file) => this.#toNode(file)) ?? [];
+		const hasNextPage = result.data.nextPageToken != null;
+		const total = cursor * limit + data.length + (hasNextPage ? limit : 0);
+		return {
+			data,
+			pagination: {
+				total,
+				totalPages: Math.max(1, Math.ceil(total / limit)),
+				limit,
+				hasNextPage,
+				hasPreviousPage: cursor > 0,
+				cursor,
+				nextCursor: hasNextPage ? cursor + 1 : null,
+				previousCursor: cursor > 0 ? cursor - 1 : null
+			}
+		};
+	}
+	/**
+	* Lists one page of Google Drive nodes for a tree/folder view.
+	*
+	* The public input uses the shared table-query shape: pagination, sorting,
+	* search, and drive filters. This method translates that input into the internal
+	* Google Drive list request shape used by `#listNodes`.
+	*
+	* Google Drive does not expose a native tree endpoint. This returns only the
+	* direct children for the requested `parentId`; recursive traversal is handled
+	* by `getNodeChildren`.
+	*/
+	async listTree(input) {
+		return this.#listNodes({
+			namespace: input.filters.namespace,
+			limit: input.limit,
+			cursor: input.cursor,
+			orderBy: this.#orderBy(input),
+			q: this.#buildQuery({
+				namespace: input.filters.namespace,
+				parentId: input.filters.parentId,
+				nodeIds: input.filters.nodeIds,
+				types: input.filters.types,
+				contentTypes: input.filters.contentTypes,
+				isArchived: input.filters.isArchived,
+				search: input.search
+			})
+		});
+	}
+	/**
+	* Walks from a Google Drive node up through its parent chain.
+	*
+	* Google Drive only exposes direct parents, so breadcrumbs must be resolved one
+	* node at a time. The `seen` set prevents accidental infinite loops if Google
+	* ever returns cyclic or inconsistent parent metadata.
+	*
+	* `seen` is treated immutably so each recursive call receives its own traversal
+	* state instead of mutating caller-owned state.
+	*/
+	async #walkParents(currentId, namespace, depth = 0, seen = /* @__PURE__ */ new Set()) {
+		if (!currentId || seen.has(currentId)) return [];
+		const node = await this.getNodeById(currentId);
+		if (!node || node.namespace !== namespace) return [];
+		const nextSeen = new Set([...seen, node.id]);
+		return [{
+			id: node.id,
+			name: node.name,
+			parentId: node.parentId,
+			depth
+		}, ...await this.#walkParents(node.parentId, namespace, depth + 1, nextSeen)];
+	}
+	/**
+	* Resolves the breadcrumb parent chain for a Google Drive node.
+	*
+	* A `null` id represents the namespace root and therefore has no parent chain.
+	* The returned list is ordered from the root-most ancestor to the requested
+	* node, matching breadcrumb display order.
+	*/
+	async getFolderParents(input) {
+		if (!input.id) return [];
+		return (await this.#walkParents(input.id, input.namespace)).toSorted((a, b) => Number(b.depth) - Number(a.depth));
+	}
+	/**
+	* Walks a Google Drive subtree breadth-first.
+	*
+	* Google Drive has no recursive children endpoint, so folder descendants must be
+	* loaded one folder at a time. The returned rows include the starting nodes and
+	* all descendants with their relative depth.
+	*/
+	async #walkChildren(queue, seen = /* @__PURE__ */ new Set()) {
+		const [current, ...rest] = queue;
+		if (!current) return [];
+		if (seen.has(current.id)) return this.#walkChildren(rest, seen);
+		const node = await this.getNodeById(current.id);
+		if (!node) return this.#walkChildren(rest, seen);
+		const nextSeen = new Set([...seen, node.id]);
+		const currentChild = {
+			id: node.id,
+			type: node.type,
+			parentId: node.parentId,
+			depth: current.depth
+		};
+		if (node.type !== "folder") return [currentChild, ...await this.#walkChildren(rest, nextSeen)];
+		const children = await this.#listChildren({ filters: {
+			namespace: node.namespace,
+			parentId: node.id,
+			isArchived: false
+		} });
+		const nextQueue = [...rest, ...children.map((child) => ({
+			id: child.id,
+			depth: current.depth + 1
+		}))];
+		return [currentChild, ...await this.#walkChildren(nextQueue, nextSeen)];
+	}
+	/**
+	* Resolves the subtree for one or more Google Drive nodes.
+	*/
+	async getNodeChildren(ids) {
+		const uniqueIds = Array.from(new Set(ids));
+		return this.#walkChildren(uniqueIds.map((id) => ({
+			id,
+			depth: 0
+		})));
+	}
+	/**
+	* Creates a Google Drive folder in the requested parent.
+	*
+	* Google Drive represents folders as files with the special folder MIME type.
+	* Creating a folder therefore uses the same `files.create` endpoint as file
+	* uploads, but without a media body.
+	*
+	* A `null` or missing `parentId` means "create in the namespace root", where the
+	* namespace is the shared drive id/root folder used by this provider.
+	*/
+	async createFolder(input) {
+		const result = await this.client.files.create({
+			requestBody: {
+				name: input.name,
+				parents: [input.parentId ?? input.namespace],
+				mimeType: GOOGLE_DRIVE_FOLDER_MIME_TYPE
+			},
+			supportsAllDrives: true,
+			fields: GOOGLE_DRIVE_NODE_FIELDS
+		});
+		return this.#toNode(result.data);
+	}
+	/**
+	* Uploads a file body to Google Drive and returns the created node.
+	*
+	* Google Drive creates files through `files.create` with two parts:
+	* metadata in `requestBody` and the actual file content in `media.body`.
+	*
+	* A `null` or missing `parentId` means "upload to the namespace root", where the
+	* namespace is the Google shared drive/root id used by this provider.
+	*
+	* The input body can be a provider-neutral object body type. `toReadable`
+	* normalizes it into a Node.js readable stream because the Google API client
+	* expects stream-compatible media bodies.
+	*/
+	async uploadFile(input) {
+		const result = await this.client.files.create({
+			requestBody: {
+				name: input.name,
+				parents: [input.parentId ?? input.namespace],
+				mimeType: input.contentType ?? void 0
+			},
+			media: {
+				mimeType: input.contentType ?? void 0,
+				body: toGoogleDriveReadable(input.body)
+			},
+			supportsAllDrives: true,
+			fields: GOOGLE_DRIVE_NODE_FIELDS
+		});
+		return this.#toNode(result.data);
+	}
+	/**
+	* Updates mutable Google Drive node metadata.
+	*
+	* Google Drive uses `files.update` for metadata changes such as renaming and
+	* moving a file/folder to or from the trash. The shared Drive API calls this
+	* soft-delete state "archived"; Google Drive exposes it as `trashed`, so
+	* `data.isArchived` is translated directly to Google's `trashed` field.
+	*
+	* Parent changes are intentionally not handled here. Moving a node requires
+	* Google Drive's `addParents`/`removeParents` API and should go through
+	* `moveNode` instead.
+	*/
+	async updateNode(id, data) {
+		const result = await this.client.files.update({
+			fileId: id,
+			requestBody: {
+				name: data.name,
+				trashed: data.isArchived
+			},
+			supportsAllDrives: true,
+			fields: GOOGLE_DRIVE_NODE_FIELDS
+		});
+		return this.#toNode(result.data);
+	}
+	/**
+	* Moves a Google Drive node to another parent folder.
+	*
+	* Google Drive does not allow parent changes through the normal metadata
+	* `requestBody`. Moving requires `addParents` and `removeParents` on
+	* `files.update`, so this operation is intentionally separate from `updateNode`.
+	*
+	* A `null` parent means "move to the namespace root". For this provider, the
+	* namespace is the Google shared drive/root id.
+	*/
+	async moveNode(input) {
+		const node = await this.getNodeById(input.id);
+		if (!node) throw new ServerError("NOT_FOUND", { message: "Node not found" });
+		if (node.readonly) throw new ServerError("BAD_REQUEST", { message: "Node is readonly and cannot be changed" });
+		if (input.parentId === input.id) throw new ServerError("BAD_REQUEST", { message: "Node cannot be moved into itself" });
+		if (input.parentId) {
+			if ((await this.getNodeChildren([input.id])).some((child) => child.id === input.parentId)) throw new ServerError("BAD_REQUEST", { message: "Node cannot be moved into one of its descendants" });
+		}
+		const result = await this.client.files.update({
+			fileId: input.id,
+			addParents: input.parentId ?? node.namespace,
+			removeParents: node.googleParents.join(",") || void 0,
+			supportsAllDrives: true,
+			fields: GOOGLE_DRIVE_NODE_FIELDS
+		});
+		return this.#toNode(result.data);
+	}
+	/**
+	* Updates the Google Drive trash state for multiple nodes.
+	*
+	* Google Drive exposes archive/restore behavior through the `trashed` metadata
+	* field on `files.update`. Each node requires a separate API request, so updates
+	* are executed in parallel after duplicate ids are removed.
+	*/
+	async #setTrashed(ids, trashed) {
+		const uniqueIds = [...new Set(ids)];
+		return (await Promise.all(uniqueIds.map((id) => this.client.files.update({
+			fileId: id,
+			requestBody: { trashed },
+			supportsAllDrives: true,
+			fields: GOOGLE_DRIVE_NODE_FIELDS
+		})))).map((result) => this.#toNode(result.data));
+	}
+	/**
+	* Moves Google Drive nodes to trash.
+	*
+	* The shared Drive API calls this "archive", while Google Drive calls the same
+	* state `trashed`. This is a soft-delete operation; nodes can be restored with
+	* `restoreNodes`.
+	*/
+	async archiveNodes(ids) {
+		return this.#setTrashed(ids, true);
+	}
+	/**
+	* Restores Google Drive nodes from trash.
+	*
+	* This reverses `archiveNodes` by setting Google Drive's `trashed` flag back to
+	* `false`.
+	*/
+	async restoreNodes(ids) {
+		return this.#setTrashed(ids, false);
+	}
+	/**
+	* Permanently deletes a Google Drive node.
+	*
+	* This uses Google Drive `files.delete`, which removes the file/folder rather
+	* than moving it to trash. Soft deletion/trashing should go through the archive
+	* method instead.
+	*/
+	async deleteNode(id) {
+		await this.client.files.delete({
+			fileId: id,
+			supportsAllDrives: true
+		});
+	}
+	/**
+	* Permanently deletes multiple Google Drive nodes.
+	*
+	* Duplicate ids are removed before issuing delete requests so the same Google
+	* file is not deleted more than once. Deletions are executed in parallel because
+	* Google Drive exposes deletion as one request per file id.
+	*
+	* This is a hard delete. Soft deletion/trashing should go through the archive
+	* method instead.
+	*/
+	async deleteNodes(ids) {
+		const uniqueIds = [...new Set(ids)];
+		await Promise.all(uniqueIds.map((id) => this.client.files.delete({
+			fileId: id,
+			supportsAllDrives: true
+		})));
+	}
+	/**
+	* Converts raw Google Drive file metadata into the provider's normalized node DTO.
+	*
+	* Google Drive API responses are loosely typed and may omit fields that our
+	* drive abstraction requires, such as `id` or a namespace/root identifier. Those
+	* cases indicate an invalid provider response rather than a caller error, so
+	* they are normalized to an internal server error.
+	*
+	* Any unexpected mapping error is rethrown so it can be handled by the normal
+	* server error boundary/logging path.
+	*/
+	#toNode(file) {
+		try {
+			return GoogleDriveNodeDTO.create({ file });
+		} catch (error) {
+			if (error instanceof Error && ["Google Drive file has no id", "Google Drive file has no namespace"].includes(error.message)) throw new ServerError("INTERNAL_SERVER_ERROR", { message: error.message });
+			throw error;
+		}
+	}
+};
+
+//#endregion
+export { GoogleDrive };
+//# sourceMappingURL=service.server.mjs.map