@tulip-systems/drive 0.8.1 → 0.8.3

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

@@ -0,0 +1,185 @@
+import { DriveArchive, DriveDirectUpload, DriveNodeMutations, DriveReader } from "../../../lib/contracts.mjs";
+import { CreateGoogleDriveFolderInput, GetGoogleDriveNodesByParentIdSchema, GoogleDriveNode, GoogleDriveNodeChild, GoogleDriveNodeWithChildren, ListGoogleDriveTreeSchema, UpdateGoogleDriveNodeInput, UploadGoogleDriveFileInput } 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 { drive_v3 } from "googleapis";
+import { Database } from "@tulip-systems/core/database/server";
+
+//#region src/providers/google/lib/service.server.d.ts
+/**
+ * Drive Service Config
+ */
+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.
+ */
+declare class GoogleDrive<TSchema extends TDatabaseSchema> implements DriveReader<GoogleDriveNode, GoogleDriveNodeWithChildren, GoogleDriveNodeChild>, DriveNodeMutations<GoogleDriveNode>, DriveDirectUpload<GoogleDriveNode, ObjectBodyInput>, DriveArchive<GoogleDriveNode> {
+  #private;
+  readonly client: drive_v3.Drive;
+  constructor(config: GoogleDriveConfig<TSchema>);
+  /**
+   * 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.
+   */
+  getNodeById(id: string): Promise<GoogleDriveNode | null>;
+  /**
+   * 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`.
+   */
+  getNodeWithChildren(input: {
+    id: string;
+    namespace: string;
+  }): Promise<GoogleDriveNodeWithChildren | null>;
+  /**
+   * 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`.
+   */
+  getNodesByParentId(input: GetGoogleDriveNodesByParentIdSchema): Promise<GoogleDriveNode[]>;
+  /**
+   * 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`.
+   */
+  listTree(input: ListGoogleDriveTreeSchema): Promise<TableQueryResponse<GoogleDriveNode>>;
+  /**
+   * 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.
+   */
+  getFolderParents(input: {
+    id: string | null;
+    namespace: string;
+  }): Promise<Array<Pick<GoogleDriveNode, "id" | "name" | "parentId"> & {
+    depth: number;
+  }>>;
+  /**
+   * Resolves the subtree for one or more Google Drive nodes.
+   */
+  getNodeChildren(ids: string[]): Promise<GoogleDriveNodeChild[]>;
+  /**
+   * 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.
+   */
+  createFolder(input: CreateGoogleDriveFolderInput): Promise<GoogleDriveNode>;
+  /**
+   * 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.
+   */
+  uploadFile(input: UploadGoogleDriveFileInput & {
+    body: ObjectBodyInput;
+  }): Promise<GoogleDriveNode>;
+  /**
+   * 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.
+   */
+  updateNode(id: string, data: UpdateGoogleDriveNodeInput): Promise<GoogleDriveNode>;
+  /**
+   * 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.
+   */
+  moveNode(input: {
+    id: string;
+    parentId: string | null;
+  }): Promise<GoogleDriveNode>;
+  /**
+   * 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`.
+   */
+  archiveNodes(ids: string[]): Promise<GoogleDriveNode[]>;
+  /**
+   * Restores Google Drive nodes from trash.
+   *
+   * This reverses `archiveNodes` by setting Google Drive's `trashed` flag back to
+   * `false`.
+   */
+  restoreNodes(ids: string[]): Promise<GoogleDriveNode[]>;
+  /**
+   * 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.
+   */
+  deleteNode(id: string): Promise<void>;
+  /**
+   * 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.
+   */
+  deleteNodes(ids: string[]): Promise<void>;
+}
+//#endregion
+export { GoogleDrive, GoogleDriveConfig };