drivekit 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -129,6 +129,8 @@ interface UploadOptions {
129
129
  /** Custom properties / metadata */
130
130
  properties?: Record<string, string>;
131
131
  appProperties?: Record<string, string>;
132
+ /** Optional AbortSignal for instant operation cancellation */
133
+ signal?: AbortSignal;
132
134
  }
133
135
  /**
134
136
  * File download parameters
@@ -140,6 +142,8 @@ interface DownloadOptions {
140
142
  onProgress?: (progress: DownloadProgress) => void;
141
143
  /** Export MIME type for Google Workspace documents */
142
144
  exportMimeType?: string;
145
+ /** Optional AbortSignal for instant operation cancellation */
146
+ signal?: AbortSignal;
143
147
  }
144
148
  /**
145
149
  * Permission role types
@@ -405,6 +409,84 @@ declare class SmartSyncEngine {
405
409
  }): Promise<PullResult>;
406
410
  }
407
411
 
412
+ /**
413
+ * Fluent reference to a specific file in Google Drive
414
+ */
415
+ declare class DriveFileRef {
416
+ private drive;
417
+ readonly pathOrId: string;
418
+ constructor(drive: DriveKit, pathOrId: string);
419
+ /** Gets file metadata */
420
+ get(): Promise<DriveApiFile>;
421
+ /** Checks if the file exists */
422
+ exists(): Promise<boolean>;
423
+ /** Reads file as UTF-8 string */
424
+ getText(): Promise<string>;
425
+ /** Reads and parses JSON file */
426
+ getJson<T = any>(): Promise<T>;
427
+ /** Downloads the file to destination */
428
+ download(optionsOrDestination?: string | DownloadOptions): Promise<any>;
429
+ /** Moves the file to a new folder path or ID */
430
+ moveTo(newParentPathOrId: string): Promise<DriveApiFile>;
431
+ /** Copies the file to a target directory */
432
+ copyTo(parentPathOrId?: string, newName?: string): Promise<DriveApiFile>;
433
+ /** Renames the file */
434
+ rename(newName: string): Promise<DriveApiFile>;
435
+ /** Deletes the file (or moves to trash if permanent is false) */
436
+ delete(permanent?: boolean): Promise<void>;
437
+ /** Moves file to trash */
438
+ trash(): Promise<void>;
439
+ /** Shares file */
440
+ share(options: ShareOptions): Promise<DriveApiPermission>;
441
+ /** Makes file publicly accessible */
442
+ sharePublic(role?: 'reader' | 'commenter' | 'writer'): Promise<{
443
+ fileId: string;
444
+ previewLink: string;
445
+ directDownloadLink: string;
446
+ }>;
447
+ /** Gets public/preview links */
448
+ getLink(): Promise<{
449
+ previewLink: string;
450
+ directDownloadLink: string;
451
+ }>;
452
+ }
453
+ /**
454
+ * Fluent reference to a specific folder in Google Drive
455
+ */
456
+ declare class DriveFolderRef {
457
+ private drive;
458
+ readonly pathOrId: string;
459
+ constructor(drive: DriveKit, pathOrId: string);
460
+ /** Lists contents of this folder */
461
+ ls(): Promise<DriveApiFile[]>;
462
+ /** Ensures this folder and subpaths exist (mkdir -p) */
463
+ mkdirp(subPath?: string): Promise<string>;
464
+ /** Uploads a file directly into this folder */
465
+ upload(source: UploadOptions['source'], options?: Omit<UploadOptions, 'source' | 'parent'>): Promise<DriveApiFile>;
466
+ /** Synchronizes a local directory into this remote folder */
467
+ syncFrom(localDir: string, options?: Parameters<DriveKit['syncFolder']>[2]): Promise<SyncResult>;
468
+ /** Pulls this remote folder down to local directory */
469
+ pullTo(localDestinationDir: string, options?: Parameters<DriveKit['pull']>[2]): Promise<PullResult>;
470
+ /** Watches this folder for real-time changes */
471
+ watch(options?: Omit<WatcherOptions, 'folderId'>): Promise<DriveWatcher>;
472
+ }
473
+
474
+ interface DriveKitPlugin {
475
+ name: string;
476
+ beforeUpload?: (options: UploadOptions) => Promise<UploadOptions | void> | UploadOptions | void;
477
+ afterUpload?: (file: DriveApiFile) => Promise<DriveApiFile | void> | DriveApiFile | void;
478
+ beforeDownload?: (fileId: string, options: DownloadOptions) => Promise<DownloadOptions | void> | DownloadOptions | void;
479
+ afterDownload?: (result: any) => Promise<any | void> | any | void;
480
+ }
481
+ declare class PluginManager {
482
+ private plugins;
483
+ use(plugin: DriveKitPlugin): this;
484
+ runBeforeUpload(options: UploadOptions): Promise<UploadOptions>;
485
+ runAfterUpload(file: DriveApiFile): Promise<DriveApiFile>;
486
+ runBeforeDownload(fileId: string, options: DownloadOptions): Promise<DownloadOptions>;
487
+ runAfterDownload(result: any): Promise<any>;
488
+ }
489
+
408
490
  declare class DriveKit {
409
491
  private options;
410
492
  private authenticator;
@@ -413,7 +495,20 @@ declare class DriveKit {
413
495
  private uploaderInstance;
414
496
  private downloaderInstance;
415
497
  private rootFolderId;
498
+ private pluginManager;
416
499
  constructor(options?: DriveKitOptions);
500
+ /**
501
+ * Registers a middleware plugin into DriveKit lifecycle
502
+ */
503
+ use(plugin: DriveKitPlugin): this;
504
+ /**
505
+ * Returns a fluent, chained reference to a specific file
506
+ */
507
+ file(pathOrId: string): DriveFileRef;
508
+ /**
509
+ * Returns a fluent, chained reference to a specific folder
510
+ */
511
+ folder(pathOrId: string): DriveFolderRef;
417
512
  /**
418
513
  * Initializes the Google Drive API client (lazy-loaded if not called explicitly)
419
514
  */
@@ -466,13 +561,7 @@ declare class DriveKit {
466
561
  * - Progress events
467
562
  * - Saves directly to file or returns Readable Stream
468
563
  */
469
- download(fileIdOrPath: string, options?: DownloadOptions): Promise<{
470
- filePath?: string;
471
- stream?: NodeJS.ReadableStream;
472
- name: string;
473
- mimeType: string;
474
- size?: number;
475
- }>;
564
+ download(fileIdOrPath: string, options?: DownloadOptions): Promise<any>;
476
565
  /**
477
566
  * Gets file metadata
478
567
  */
@@ -809,6 +898,20 @@ declare class ConcurrencyPool {
809
898
  map<Item, Result>(items: Item[], fn: (item: Item, index: number) => Promise<Result>): Promise<Result[]>;
810
899
  }
811
900
 
901
+ /**
902
+ * Creates an OSC 8 clickable hyperlink in supported modern terminals (macOS Terminal, iTerm2, VS Code, etc.)
903
+ */
904
+ declare function terminalLink(text: string, url: string): string;
905
+ /**
906
+ * Renders a visually stunning, colored file table with clickable links
907
+ */
908
+ declare function renderFileRow(item: DriveApiFile, index?: number): string;
909
+ declare function getFileIcon(mimeType: string): string;
910
+ /**
911
+ * Interactive Keyboard-driven Google Drive File Explorer (TUI)
912
+ */
913
+ declare function runInteractiveExplorer(client: DriveKit, initialFolder?: string): Promise<void>;
914
+
812
915
  /**
813
916
  * Formats bytes to human-readable string (KB, MB, GB)
814
917
  */
@@ -890,4 +993,4 @@ declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Pro
890
993
  */
891
994
  declare function createDrive(options?: DriveKitOptions): Promise<DriveKit>;
892
995
 
893
- export { type BrowserLoginOptions, ConcurrencyPool, DEFAULT_CHUNK_SIZE, DEFAULT_EXPORT_MIMES, DEFAULT_SCOPES, type DownloadOptions, type DownloadProgress, Downloader, type DriveApiFile, type DriveApiFileList, type DriveApiPermission, DriveAuthError, DriveAuthenticator, DriveKit, type DriveKitAuthConfig, DriveKitError, type DriveKitOptions, DriveNotFoundError, DriveQueryBuilder, DriveRateLimitError, DriveUploadError, DriveWatcher, type DuplicateGroup, type FileChangeEvent, GOOGLE_WORKSPACE_MIME_TYPES, type LoginResult, MIN_CHUNK_SIZE, MULTIPART_THRESHOLD, PathResolver, type PermissionRole, type PermissionType, type PullResult, ResumableUploader, type RetryOptions, type ShareOptions, SmartSyncEngine, StorageCleaner, type SyncResult, type UploadOptions, type UploadProgress, type WatcherOptions, calculateFileMd5, createDrive, DriveKit as default, formatBytes, formatDuration, formatSpeed, getExtensionForMime, isGoogleWorkspaceDoc, isRetryableError, loginWithBrowser, lookupMimeType, withRetry };
996
+ export { type BrowserLoginOptions, ConcurrencyPool, DEFAULT_CHUNK_SIZE, DEFAULT_EXPORT_MIMES, DEFAULT_SCOPES, type DownloadOptions, type DownloadProgress, Downloader, type DriveApiFile, type DriveApiFileList, type DriveApiPermission, DriveAuthError, DriveAuthenticator, DriveFileRef, DriveFolderRef, DriveKit, type DriveKitAuthConfig, DriveKitError, type DriveKitOptions, type DriveKitPlugin, DriveNotFoundError, DriveQueryBuilder, DriveRateLimitError, DriveUploadError, DriveWatcher, type DuplicateGroup, type FileChangeEvent, GOOGLE_WORKSPACE_MIME_TYPES, type LoginResult, MIN_CHUNK_SIZE, MULTIPART_THRESHOLD, PathResolver, type PermissionRole, type PermissionType, PluginManager, type PullResult, ResumableUploader, type RetryOptions, type ShareOptions, SmartSyncEngine, StorageCleaner, type SyncResult, type UploadOptions, type UploadProgress, type WatcherOptions, calculateFileMd5, createDrive, DriveKit as default, formatBytes, formatDuration, formatSpeed, getExtensionForMime, getFileIcon, isGoogleWorkspaceDoc, isRetryableError, loginWithBrowser, lookupMimeType, renderFileRow, runInteractiveExplorer, terminalLink, withRetry };
package/dist/index.d.ts CHANGED
@@ -129,6 +129,8 @@ interface UploadOptions {
129
129
  /** Custom properties / metadata */
130
130
  properties?: Record<string, string>;
131
131
  appProperties?: Record<string, string>;
132
+ /** Optional AbortSignal for instant operation cancellation */
133
+ signal?: AbortSignal;
132
134
  }
133
135
  /**
134
136
  * File download parameters
@@ -140,6 +142,8 @@ interface DownloadOptions {
140
142
  onProgress?: (progress: DownloadProgress) => void;
141
143
  /** Export MIME type for Google Workspace documents */
142
144
  exportMimeType?: string;
145
+ /** Optional AbortSignal for instant operation cancellation */
146
+ signal?: AbortSignal;
143
147
  }
144
148
  /**
145
149
  * Permission role types
@@ -405,6 +409,84 @@ declare class SmartSyncEngine {
405
409
  }): Promise<PullResult>;
406
410
  }
407
411
 
412
+ /**
413
+ * Fluent reference to a specific file in Google Drive
414
+ */
415
+ declare class DriveFileRef {
416
+ private drive;
417
+ readonly pathOrId: string;
418
+ constructor(drive: DriveKit, pathOrId: string);
419
+ /** Gets file metadata */
420
+ get(): Promise<DriveApiFile>;
421
+ /** Checks if the file exists */
422
+ exists(): Promise<boolean>;
423
+ /** Reads file as UTF-8 string */
424
+ getText(): Promise<string>;
425
+ /** Reads and parses JSON file */
426
+ getJson<T = any>(): Promise<T>;
427
+ /** Downloads the file to destination */
428
+ download(optionsOrDestination?: string | DownloadOptions): Promise<any>;
429
+ /** Moves the file to a new folder path or ID */
430
+ moveTo(newParentPathOrId: string): Promise<DriveApiFile>;
431
+ /** Copies the file to a target directory */
432
+ copyTo(parentPathOrId?: string, newName?: string): Promise<DriveApiFile>;
433
+ /** Renames the file */
434
+ rename(newName: string): Promise<DriveApiFile>;
435
+ /** Deletes the file (or moves to trash if permanent is false) */
436
+ delete(permanent?: boolean): Promise<void>;
437
+ /** Moves file to trash */
438
+ trash(): Promise<void>;
439
+ /** Shares file */
440
+ share(options: ShareOptions): Promise<DriveApiPermission>;
441
+ /** Makes file publicly accessible */
442
+ sharePublic(role?: 'reader' | 'commenter' | 'writer'): Promise<{
443
+ fileId: string;
444
+ previewLink: string;
445
+ directDownloadLink: string;
446
+ }>;
447
+ /** Gets public/preview links */
448
+ getLink(): Promise<{
449
+ previewLink: string;
450
+ directDownloadLink: string;
451
+ }>;
452
+ }
453
+ /**
454
+ * Fluent reference to a specific folder in Google Drive
455
+ */
456
+ declare class DriveFolderRef {
457
+ private drive;
458
+ readonly pathOrId: string;
459
+ constructor(drive: DriveKit, pathOrId: string);
460
+ /** Lists contents of this folder */
461
+ ls(): Promise<DriveApiFile[]>;
462
+ /** Ensures this folder and subpaths exist (mkdir -p) */
463
+ mkdirp(subPath?: string): Promise<string>;
464
+ /** Uploads a file directly into this folder */
465
+ upload(source: UploadOptions['source'], options?: Omit<UploadOptions, 'source' | 'parent'>): Promise<DriveApiFile>;
466
+ /** Synchronizes a local directory into this remote folder */
467
+ syncFrom(localDir: string, options?: Parameters<DriveKit['syncFolder']>[2]): Promise<SyncResult>;
468
+ /** Pulls this remote folder down to local directory */
469
+ pullTo(localDestinationDir: string, options?: Parameters<DriveKit['pull']>[2]): Promise<PullResult>;
470
+ /** Watches this folder for real-time changes */
471
+ watch(options?: Omit<WatcherOptions, 'folderId'>): Promise<DriveWatcher>;
472
+ }
473
+
474
+ interface DriveKitPlugin {
475
+ name: string;
476
+ beforeUpload?: (options: UploadOptions) => Promise<UploadOptions | void> | UploadOptions | void;
477
+ afterUpload?: (file: DriveApiFile) => Promise<DriveApiFile | void> | DriveApiFile | void;
478
+ beforeDownload?: (fileId: string, options: DownloadOptions) => Promise<DownloadOptions | void> | DownloadOptions | void;
479
+ afterDownload?: (result: any) => Promise<any | void> | any | void;
480
+ }
481
+ declare class PluginManager {
482
+ private plugins;
483
+ use(plugin: DriveKitPlugin): this;
484
+ runBeforeUpload(options: UploadOptions): Promise<UploadOptions>;
485
+ runAfterUpload(file: DriveApiFile): Promise<DriveApiFile>;
486
+ runBeforeDownload(fileId: string, options: DownloadOptions): Promise<DownloadOptions>;
487
+ runAfterDownload(result: any): Promise<any>;
488
+ }
489
+
408
490
  declare class DriveKit {
409
491
  private options;
410
492
  private authenticator;
@@ -413,7 +495,20 @@ declare class DriveKit {
413
495
  private uploaderInstance;
414
496
  private downloaderInstance;
415
497
  private rootFolderId;
498
+ private pluginManager;
416
499
  constructor(options?: DriveKitOptions);
500
+ /**
501
+ * Registers a middleware plugin into DriveKit lifecycle
502
+ */
503
+ use(plugin: DriveKitPlugin): this;
504
+ /**
505
+ * Returns a fluent, chained reference to a specific file
506
+ */
507
+ file(pathOrId: string): DriveFileRef;
508
+ /**
509
+ * Returns a fluent, chained reference to a specific folder
510
+ */
511
+ folder(pathOrId: string): DriveFolderRef;
417
512
  /**
418
513
  * Initializes the Google Drive API client (lazy-loaded if not called explicitly)
419
514
  */
@@ -466,13 +561,7 @@ declare class DriveKit {
466
561
  * - Progress events
467
562
  * - Saves directly to file or returns Readable Stream
468
563
  */
469
- download(fileIdOrPath: string, options?: DownloadOptions): Promise<{
470
- filePath?: string;
471
- stream?: NodeJS.ReadableStream;
472
- name: string;
473
- mimeType: string;
474
- size?: number;
475
- }>;
564
+ download(fileIdOrPath: string, options?: DownloadOptions): Promise<any>;
476
565
  /**
477
566
  * Gets file metadata
478
567
  */
@@ -809,6 +898,20 @@ declare class ConcurrencyPool {
809
898
  map<Item, Result>(items: Item[], fn: (item: Item, index: number) => Promise<Result>): Promise<Result[]>;
810
899
  }
811
900
 
901
+ /**
902
+ * Creates an OSC 8 clickable hyperlink in supported modern terminals (macOS Terminal, iTerm2, VS Code, etc.)
903
+ */
904
+ declare function terminalLink(text: string, url: string): string;
905
+ /**
906
+ * Renders a visually stunning, colored file table with clickable links
907
+ */
908
+ declare function renderFileRow(item: DriveApiFile, index?: number): string;
909
+ declare function getFileIcon(mimeType: string): string;
910
+ /**
911
+ * Interactive Keyboard-driven Google Drive File Explorer (TUI)
912
+ */
913
+ declare function runInteractiveExplorer(client: DriveKit, initialFolder?: string): Promise<void>;
914
+
812
915
  /**
813
916
  * Formats bytes to human-readable string (KB, MB, GB)
814
917
  */
@@ -890,4 +993,4 @@ declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Pro
890
993
  */
891
994
  declare function createDrive(options?: DriveKitOptions): Promise<DriveKit>;
892
995
 
893
- export { type BrowserLoginOptions, ConcurrencyPool, DEFAULT_CHUNK_SIZE, DEFAULT_EXPORT_MIMES, DEFAULT_SCOPES, type DownloadOptions, type DownloadProgress, Downloader, type DriveApiFile, type DriveApiFileList, type DriveApiPermission, DriveAuthError, DriveAuthenticator, DriveKit, type DriveKitAuthConfig, DriveKitError, type DriveKitOptions, DriveNotFoundError, DriveQueryBuilder, DriveRateLimitError, DriveUploadError, DriveWatcher, type DuplicateGroup, type FileChangeEvent, GOOGLE_WORKSPACE_MIME_TYPES, type LoginResult, MIN_CHUNK_SIZE, MULTIPART_THRESHOLD, PathResolver, type PermissionRole, type PermissionType, type PullResult, ResumableUploader, type RetryOptions, type ShareOptions, SmartSyncEngine, StorageCleaner, type SyncResult, type UploadOptions, type UploadProgress, type WatcherOptions, calculateFileMd5, createDrive, DriveKit as default, formatBytes, formatDuration, formatSpeed, getExtensionForMime, isGoogleWorkspaceDoc, isRetryableError, loginWithBrowser, lookupMimeType, withRetry };
996
+ export { type BrowserLoginOptions, ConcurrencyPool, DEFAULT_CHUNK_SIZE, DEFAULT_EXPORT_MIMES, DEFAULT_SCOPES, type DownloadOptions, type DownloadProgress, Downloader, type DriveApiFile, type DriveApiFileList, type DriveApiPermission, DriveAuthError, DriveAuthenticator, DriveFileRef, DriveFolderRef, DriveKit, type DriveKitAuthConfig, DriveKitError, type DriveKitOptions, type DriveKitPlugin, DriveNotFoundError, DriveQueryBuilder, DriveRateLimitError, DriveUploadError, DriveWatcher, type DuplicateGroup, type FileChangeEvent, GOOGLE_WORKSPACE_MIME_TYPES, type LoginResult, MIN_CHUNK_SIZE, MULTIPART_THRESHOLD, PathResolver, type PermissionRole, type PermissionType, PluginManager, type PullResult, ResumableUploader, type RetryOptions, type ShareOptions, SmartSyncEngine, StorageCleaner, type SyncResult, type UploadOptions, type UploadProgress, type WatcherOptions, calculateFileMd5, createDrive, DriveKit as default, formatBytes, formatDuration, formatSpeed, getExtensionForMime, getFileIcon, isGoogleWorkspaceDoc, isRetryableError, loginWithBrowser, lookupMimeType, renderFileRow, runInteractiveExplorer, terminalLink, withRetry };