@tulip-systems/drive 0.7.0

package/src/providers/google/lib/service.server.ts

@@ -0,0 +1,792 @@
+import type { TDatabaseSchema } from "@tulip-systems/core/config";
+import type { TableQuerySchema } from "@tulip-systems/core/data-tables";
+import type { TableQueryResponse } from "@tulip-systems/core/data-tables/server";
+import type { Database } from "@tulip-systems/core/database/server";
+import { ServerError } from "@tulip-systems/core/router/server";
+import type { ObjectBodyInput } from "@tulip-systems/core/storage";
+import { type drive_v3, google } from "googleapis";
+import type {
+  DriveArchive,
+  DriveDirectUpload,
+  DriveNodeMutations,
+  DriveReader,
+} from "@/lib/contracts";
+import { GOOGLE_DRIVE_FOLDER_MIME_TYPE, GOOGLE_DRIVE_NODE_FIELDS } from "./constants";
+import { GoogleDriveNodeDTO } from "./dto";
+import { escapeGoogleDriveQueryValue, isGoogleNotFound, toGoogleDriveReadable } from "./helpers";
+import type {
+  CreateGoogleDriveFolderInput,
+  GetGoogleDriveNodesByParentIdSchema,
+  GoogleDriveNode,
+  GoogleDriveNodeChild,
+  GoogleDriveNodeWithChildren,
+  GoogleDriveTableFilters,
+  ListGoogleDriveTreeSchema,
+  UpdateGoogleDriveNodeInput,
+  UploadGoogleDriveFileInput,
+} from "./validators";
+
+const DEFAULT_PAGE_SIZE = 10;
+const CHILDREN_PAGE_SIZE = 1000;
+
+/**
+ * Drive Service Config
+ */
+export type GoogleDriveConfig<TSchema extends TDatabaseSchema> = Pick<drive_v3.Options, "auth"> & {
+  db: Database<TSchema>;
+};
+
+/**
+ * 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.
+ */
+export class GoogleDrive<TSchema extends TDatabaseSchema>
+  implements
+    DriveReader<GoogleDriveNode, GoogleDriveNodeWithChildren, GoogleDriveNodeChild>,
+    DriveNodeMutations<GoogleDriveNode>,
+    DriveDirectUpload<GoogleDriveNode, ObjectBodyInput>,
+    DriveArchive<GoogleDriveNode>
+{
+  readonly client: drive_v3.Drive;
+
+  constructor(config: GoogleDriveConfig<TSchema>) {
+    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: string): Promise<drive_v3.Schema$File | null> {
+    try {
+      const result = await this.client.files.get({
+        fileId: id,
+        supportsAllDrives: true,
+        fields: GOOGLE_DRIVE_NODE_FIELDS,
+      });
+
+      return result.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: string): Promise<GoogleDriveNode | null> {
+    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: Pick<TableQuerySchema, "sort" | "order">): string {
+    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: Pick<GoogleDriveTableFilters, "namespace" | "parentId">): string | null {
+    if (input.parentId === undefined) return null;
+
+    const parentId = input.parentId ?? input.namespace;
+    return `'${escapeGoogleDriveQueryValue(parentId)}' in parents`;
+  }
+
+  /**
+   * Filters results to a specific set of Google file ids.
+   */
+  #idQuery(nodeIds?: string[] | null): string | null {
+    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?: Array<"file" | "folder"> | null): string | null {
+    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?: string[] | null): string | null {
+    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?: boolean | null): string | null {
+    return `trashed = ${isArchived === true ? "true" : "false"}`;
+  }
+
+  /**
+   * Applies a name search.
+   *
+   * Google Drive supports `name contains '<value>'`, which is a substring match.
+   */
+  #searchQuery(search?: string | null): string | null {
+    if (!search) return null;
+
+    return `name contains '${escapeGoogleDriveQueryValue(search)}'`;
+  }
+
+  #buildQuery(input: GoogleDriveTableFilters & Pick<TableQuerySchema, "search">): string {
+    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): clause is string => 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: GetGoogleDriveNodesByParentIdSchema) {
+    const filters = input?.filters;
+    const files: drive_v3.Schema$File[] = [];
+    let pageToken: string | undefined;
+
+    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 ?? undefined;
+    } 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: {
+    id: string;
+    namespace: string;
+  }): Promise<GoogleDriveNodeWithChildren | null> {
+    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: GetGoogleDriveNodesByParentIdSchema): Promise<GoogleDriveNode[]> {
+    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: {
+      namespace: string;
+      q: string;
+      limit: number;
+      cursor?: number;
+      orderBy?: string;
+    },
+    remainingPages: number,
+    pageToken?: string,
+  ): Promise<{ pageToken?: string; exhausted: boolean }> {
+    if (remainingPages === 0) return { pageToken, exhausted: false };
+
+    const result = 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)",
+    });
+
+    const nextPageToken = result.data.nextPageToken ?? undefined;
+    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: {
+    namespace: string;
+    q: string;
+    limit?: number;
+    cursor?: number;
+    orderBy?: string;
+  }): Promise<TableQueryResponse<GoogleDriveNode>> {
+    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;
+
+    // Google does not expose an exact total for this query. Estimate enough rows
+    // for the current page and one possible next page so pagination remains usable.
+    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: ListGoogleDriveTreeSchema): Promise<TableQueryResponse<GoogleDriveNode>> {
+    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: string | null,
+    namespace: string,
+    depth = 0,
+    seen = new Set<string>(),
+  ): Promise<Array<Pick<GoogleDriveNode, "id" | "name" | "parentId"> & { depth: number }>> {
+    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: {
+    id: string | null;
+    namespace: string;
+  }): Promise<Array<Pick<GoogleDriveNode, "id" | "name" | "parentId"> & { depth: number }>> {
+    if (!input.id) return [];
+
+    const parents = await this.#walkParents(input.id, input.namespace);
+    return parents.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: { id: string; depth: number }[],
+    seen: ReadonlySet<string> = new Set(),
+  ): Promise<GoogleDriveNodeChild[]> {
+    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,
+    } satisfies GoogleDriveNodeChild;
+
+    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: string[]): Promise<GoogleDriveNodeChild[]> {
+    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: CreateGoogleDriveFolderInput): Promise<GoogleDriveNode> {
+    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: UploadGoogleDriveFileInput & { body: ObjectBodyInput },
+  ): Promise<GoogleDriveNode> {
+    const result = await this.client.files.create({
+      requestBody: {
+        name: input.name,
+        parents: [input.parentId ?? input.namespace],
+        mimeType: input.contentType ?? undefined,
+      },
+      media: {
+        mimeType: input.contentType ?? undefined,
+        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: string, data: UpdateGoogleDriveNodeInput): Promise<GoogleDriveNode> {
+    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: { id: string; parentId: string | null }): Promise<GoogleDriveNode> {
+    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" });
+    }
+
+    // Prevent creating cycles by moving a folder into one of its descendants.
+    if (input.parentId) {
+      const subtree = await this.getNodeChildren([input.id]);
+
+      if (subtree.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(",") || undefined,
+      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: string[], trashed: boolean): Promise<GoogleDriveNode[]> {
+    const uniqueIds = [...new Set(ids)];
+
+    const results = await Promise.all(
+      uniqueIds.map((id) =>
+        this.client.files.update({
+          fileId: id,
+          requestBody: { trashed },
+          supportsAllDrives: true,
+          fields: GOOGLE_DRIVE_NODE_FIELDS,
+        }),
+      ),
+    );
+
+    return results.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: string[]): Promise<GoogleDriveNode[]> {
+    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: string[]): Promise<GoogleDriveNode[]> {
+    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: string): Promise<void> {
+    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: string[]): Promise<void> {
+    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: drive_v3.Schema$File): GoogleDriveNode {
+    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;
+    }
+  }
+}