drivekit 1.0.2 → 1.1.0

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
@@ -1,6 +1,8 @@
1
+ import * as http from 'http';
1
2
  import { drive_v3 } from '@googleapis/drive';
2
3
  import { OAuth2Client } from 'google-auth-library';
3
4
  import { EventEmitter } from 'node:events';
5
+ import http$1 from 'node:http';
4
6
 
5
7
  interface BrowserLoginOptions {
6
8
  clientId: string;
@@ -70,6 +72,10 @@ interface DriveKitOptions {
70
72
  enablePathCache?: boolean;
71
73
  /** Cache TTL in milliseconds (default: 5 minutes) */
72
74
  pathCacheTTL?: number;
75
+ /** Enable persistent SQLite metadata cache for 0ms path resolution across sessions (default: true) */
76
+ enablePersistentCache?: boolean;
77
+ /** Custom path to the SQLite cache database file (default: ~/.drivekit/cache.db) */
78
+ cacheDatabasePath?: string;
73
79
  /** Number of retry attempts for 429/5xx errors (default: 5) */
74
80
  maxRetries?: number;
75
81
  /** Base delay for exponential backoff in ms (default: 1000) */
@@ -126,6 +132,10 @@ interface UploadOptions {
126
132
  onProgress?: (progress: UploadProgress) => void;
127
133
  /** Whether to overwrite file with same name in destination */
128
134
  overwrite?: boolean;
135
+ /** Whether to enable instant upload deduplication by file MD5 hash */
136
+ deduplicate?: boolean;
137
+ /** Alias for target file name */
138
+ filename?: string;
129
139
  /** Custom properties / metadata */
130
140
  properties?: Record<string, string>;
131
141
  appProperties?: Record<string, string>;
@@ -255,6 +265,14 @@ declare class DriveQueryBuilder {
255
265
  * Custom raw query condition
256
266
  */
257
267
  raw(condition: string): this;
268
+ /**
269
+ * Custom raw query condition (alias for raw)
270
+ */
271
+ custom(condition: string): this;
272
+ /**
273
+ * Filter: Exact MD5 checksum match
274
+ */
275
+ md5(checksum: string): this;
258
276
  /**
259
277
  * Sort ordering (e.g. 'modifiedTime desc', 'name', 'folder,modifiedTime desc')
260
278
  */
@@ -275,6 +293,10 @@ declare class DriveQueryBuilder {
275
293
  * Executes query and returns array of matching files
276
294
  */
277
295
  list(): Promise<DriveApiFile[]>;
296
+ /**
297
+ * Executes query and returns array of matching files (alias for list)
298
+ */
299
+ execute(): Promise<DriveApiFile[]>;
278
300
  /**
279
301
  * Returns the first matching file, or null if not found
280
302
  */
@@ -449,6 +471,22 @@ declare class DriveFileRef {
449
471
  previewLink: string;
450
472
  directDownloadLink: string;
451
473
  }>;
474
+ /** Returns a ReadableStream for this file, optionally with byte Range requests */
475
+ createReadStream(options?: {
476
+ start?: number;
477
+ end?: number;
478
+ }): Promise<NodeJS.ReadableStream>;
479
+ /** Grants access to a specific email with custom role and notification */
480
+ grantAccess(options: {
481
+ email: string;
482
+ role?: 'reader' | 'commenter' | 'writer';
483
+ notify?: boolean;
484
+ message?: string;
485
+ }): Promise<DriveApiPermission>;
486
+ /** Revokes access by permission ID or user email */
487
+ revokeAccess(permissionIdOrEmail: string): Promise<void>;
488
+ /** Lists all granted permissions on this file */
489
+ listPermissions(): Promise<DriveApiPermission[]>;
452
490
  }
453
491
  /**
454
492
  * Fluent reference to a specific folder in Google Drive
@@ -469,6 +507,15 @@ declare class DriveFolderRef {
469
507
  pullTo(localDestinationDir: string, options?: Parameters<DriveKit['pull']>[2]): Promise<PullResult>;
470
508
  /** Watches this folder for real-time changes */
471
509
  watch(options?: Omit<WatcherOptions, 'folderId'>): Promise<DriveWatcher>;
510
+ /** Grants access to this entire folder */
511
+ grantAccess(options: {
512
+ email: string;
513
+ role?: 'reader' | 'commenter' | 'writer';
514
+ notify?: boolean;
515
+ message?: string;
516
+ }): Promise<DriveApiPermission>;
517
+ /** Creates a writable stream directly into a file inside this folder */
518
+ createWriteStream(fileName: string, options?: Omit<UploadOptions, 'source' | 'filename' | 'parent'>): Promise<NodeJS.WritableStream>;
472
519
  }
473
520
 
474
521
  interface DriveKitPlugin {
@@ -486,6 +533,106 @@ declare class PluginManager {
486
533
  runBeforeDownload(fileId: string, options: DownloadOptions): Promise<DownloadOptions>;
487
534
  runAfterDownload(result: any): Promise<any>;
488
535
  }
536
+ /**
537
+ * Creates an official Webhook Plugin to notify external services (Slack, Discord, Telegram, Zapier)
538
+ * when uploads or downloads finish.
539
+ */
540
+ declare function createWebhookPlugin(options: {
541
+ url: string;
542
+ headers?: Record<string, string>;
543
+ events?: ('upload' | 'download')[];
544
+ }): DriveKitPlugin;
545
+ /**
546
+ * Creates an Auto-Namer Plugin to automatically prefix/suffix or timestamp files
547
+ */
548
+ declare function createAutoNamePlugin(options: {
549
+ prefix?: string;
550
+ suffix?: string;
551
+ appendTimestamp?: boolean;
552
+ }): DriveKitPlugin;
553
+
554
+ interface CacheFileEntry {
555
+ id: string;
556
+ name: string;
557
+ mimeType: string;
558
+ size?: number;
559
+ parentId?: string;
560
+ path?: string;
561
+ md5Checksum?: string;
562
+ trashed: boolean;
563
+ modifiedTime?: string;
564
+ updatedAt?: number;
565
+ }
566
+ interface CacheStats {
567
+ fileCount: number;
568
+ folderCount: number;
569
+ totalSizeBytes: number;
570
+ lastSyncTime: string | null;
571
+ databasePath: string;
572
+ }
573
+ interface IMetadataCache {
574
+ init(): void;
575
+ getById(id: string): CacheFileEntry | null;
576
+ getByPath(normalizedPath: string): CacheFileEntry | null;
577
+ getChildren(parentId: string): CacheFileEntry[];
578
+ findByMd5(md5: string): CacheFileEntry | null;
579
+ searchByName(query: string): CacheFileEntry[];
580
+ upsertFile(entry: CacheFileEntry): void;
581
+ upsertFiles(entries: CacheFileEntry[]): void;
582
+ deleteFile(id: string): void;
583
+ clear(): void;
584
+ getMeta(key: string): string | null;
585
+ setMeta(key: string, value: string): void;
586
+ getStats(): CacheStats;
587
+ close(): void;
588
+ }
589
+ /**
590
+ * High-performance SQLite-backed persistent cache for DriveKit metadata.
591
+ * Uses Node 22's built-in `node:sqlite` (DatabaseSync).
592
+ */
593
+ declare class SqliteMetadataCache implements IMetadataCache {
594
+ private db;
595
+ private dbPath;
596
+ private initialized;
597
+ private fallbackMemory?;
598
+ constructor(customPath?: string);
599
+ init(): void;
600
+ getById(id: string): CacheFileEntry | null;
601
+ getByPath(normalizedPath: string): CacheFileEntry | null;
602
+ getChildren(parentId: string): CacheFileEntry[];
603
+ findByMd5(md5: string): CacheFileEntry | null;
604
+ searchByName(query: string): CacheFileEntry[];
605
+ upsertFile(entry: CacheFileEntry): void;
606
+ upsertFiles(entries: CacheFileEntry[]): void;
607
+ deleteFile(id: string): void;
608
+ clear(): void;
609
+ getMeta(key: string): string | null;
610
+ setMeta(key: string, value: string): void;
611
+ getStats(): CacheStats;
612
+ close(): void;
613
+ private mapRow;
614
+ }
615
+ /**
616
+ * Fallback in-memory cache if SQLite is unavailable
617
+ */
618
+ declare class MemoryMetadataCache implements IMetadataCache {
619
+ private files;
620
+ private meta;
621
+ init(): void;
622
+ getById(id: string): CacheFileEntry | null;
623
+ getByPath(normalizedPath: string): CacheFileEntry | null;
624
+ getChildren(parentId: string): CacheFileEntry[];
625
+ findByMd5(md5: string): CacheFileEntry | null;
626
+ searchByName(query: string): CacheFileEntry[];
627
+ upsertFile(entry: CacheFileEntry): void;
628
+ upsertFiles(entries: CacheFileEntry[]): void;
629
+ deleteFile(id: string): void;
630
+ clear(): void;
631
+ getMeta(key: string): string | null;
632
+ setMeta(key: string, value: string): void;
633
+ getStats(): CacheStats;
634
+ close(): void;
635
+ }
489
636
 
490
637
  declare class DriveKit {
491
638
  private options;
@@ -494,6 +641,7 @@ declare class DriveKit {
494
641
  private pathResolverInstance;
495
642
  private uploaderInstance;
496
643
  private downloaderInstance;
644
+ private metadataCacheInstance;
497
645
  private rootFolderId;
498
646
  private pluginManager;
499
647
  constructor(options?: DriveKitOptions);
@@ -682,6 +830,76 @@ declare class DriveKit {
682
830
  onFileStart?: (remoteName: string, relativePath: string) => void;
683
831
  onFileComplete?: (remoteName: string, localPath: string) => void;
684
832
  }): Promise<PullResult>;
833
+ /**
834
+ * Creates a readable stream for a file, supporting partial range requests
835
+ */
836
+ createReadStream(pathOrId: string, options?: {
837
+ start?: number;
838
+ end?: number;
839
+ }): Promise<NodeJS.ReadableStream>;
840
+ /**
841
+ * Creates a writable stream directly into Google Drive
842
+ */
843
+ createWriteStream(remotePath: string, options?: Omit<UploadOptions, 'source'>): Promise<NodeJS.WritableStream>;
844
+ /**
845
+ * Returns the active persistent metadata cache instance (SQLite/Memory)
846
+ */
847
+ getMetadataCache(): Promise<IMetadataCache | null>;
848
+ /**
849
+ * Returns cache statistics (total files, folders, size, last sync)
850
+ */
851
+ getCacheStats(): Promise<CacheStats | null>;
852
+ /**
853
+ * Clears the path and metadata cache
854
+ */
855
+ clearCache(): Promise<void>;
856
+ /**
857
+ * Crawls and indexes Google Drive metadata into the local SQLite database for instant 0ms lookups
858
+ */
859
+ syncCache(options?: {
860
+ onProgress?: (scanned: number) => void;
861
+ }): Promise<CacheStats>;
862
+ /**
863
+ * Lists all Google Workspace Shared Drives accessible by current user or service account
864
+ */
865
+ listSharedDrives(options?: {
866
+ pageSize?: number;
867
+ }): Promise<{
868
+ id: string;
869
+ name: string;
870
+ }[]>;
871
+ /**
872
+ * Creates a scoped DriveKit client locked to a specific Shared Drive
873
+ */
874
+ sharedDrive(driveId: string): DriveKit;
875
+ /**
876
+ * Grants access to a specific email with custom role and notification
877
+ */
878
+ grantAccess(pathOrId: string, options: {
879
+ email: string;
880
+ role?: 'reader' | 'commenter' | 'writer';
881
+ notify?: boolean;
882
+ message?: string;
883
+ }): Promise<DriveApiPermission>;
884
+ /**
885
+ * Revokes access for a specific permission ID or email address
886
+ */
887
+ revokeAccess(pathOrId: string, permissionIdOrEmail: string): Promise<void>;
888
+ /**
889
+ * Lists all active permissions on a file or folder
890
+ */
891
+ listPermissions(pathOrId: string): Promise<DriveApiPermission[]>;
892
+ /**
893
+ * Starts an embedded WebDAV server to mount DriveKit directly in macOS Finder or Windows Explorer
894
+ */
895
+ serveWebDAV(options?: {
896
+ port?: number;
897
+ host?: string;
898
+ }): Promise<{
899
+ server: http.Server;
900
+ url: string;
901
+ close: () => Promise<void>;
902
+ }>;
685
903
  /**
686
904
  * Calculates local file MD5 hash for integrity and deduplication checks
687
905
  */
@@ -774,9 +992,11 @@ declare class PathResolver {
774
992
  private cache;
775
993
  private cacheTTL;
776
994
  private enableCache;
995
+ private metadataCache?;
777
996
  constructor(drive: drive_v3.Drive, rootFolderId?: string, options?: {
778
997
  enableCache?: boolean;
779
998
  cacheTTL?: number;
999
+ metadataCache?: IMetadataCache;
780
1000
  });
781
1001
  /**
782
1002
  * Normalizes a virtual path (e.g. "///Backups//2026/" -> "/Backups/2026")
@@ -874,6 +1094,13 @@ declare class Downloader {
874
1094
  mimeType: string;
875
1095
  size?: number;
876
1096
  }>;
1097
+ /**
1098
+ * Returns a raw ReadableStream for the file, supporting HTTP Range requests for partial content / streaming.
1099
+ */
1100
+ createReadStream(fileId: string, options?: {
1101
+ start?: number;
1102
+ end?: number;
1103
+ }): Promise<NodeJS.ReadableStream>;
877
1104
  }
878
1105
 
879
1106
  /**
@@ -898,6 +1125,20 @@ declare class ConcurrencyPool {
898
1125
  map<Item, Result>(items: Item[], fn: (item: Item, index: number) => Promise<Result>): Promise<Result[]>;
899
1126
  }
900
1127
 
1128
+ interface WebDAVServerOptions {
1129
+ port?: number;
1130
+ host?: string;
1131
+ }
1132
+ /**
1133
+ * Creates and starts a lightweight zero-dependency WebDAV server for DriveKit.
1134
+ * Allows mounting Google Drive directly in macOS Finder, Windows Explorer, or Linux.
1135
+ */
1136
+ declare function startWebDAVServer(drive: DriveKit, options?: WebDAVServerOptions): Promise<{
1137
+ server: http$1.Server;
1138
+ url: string;
1139
+ close: () => Promise<void>;
1140
+ }>;
1141
+
901
1142
  /**
902
1143
  * Creates an OSC 8 clickable hyperlink in supported modern terminals (macOS Terminal, iTerm2, VS Code, etc.)
903
1144
  */
@@ -993,4 +1234,4 @@ declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Pro
993
1234
  */
994
1235
  declare function createDrive(options?: DriveKitOptions): Promise<DriveKit>;
995
1236
 
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 };
1237
+ export { type BrowserLoginOptions, type CacheFileEntry, type CacheStats, 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 IMetadataCache, type LoginResult, MIN_CHUNK_SIZE, MULTIPART_THRESHOLD, MemoryMetadataCache, PathResolver, type PermissionRole, type PermissionType, PluginManager, type PullResult, ResumableUploader, type RetryOptions, type ShareOptions, SmartSyncEngine, SqliteMetadataCache, StorageCleaner, type SyncResult, type UploadOptions, type UploadProgress, type WatcherOptions, type WebDAVServerOptions, calculateFileMd5, createAutoNamePlugin, createDrive, createWebhookPlugin, DriveKit as default, formatBytes, formatDuration, formatSpeed, getExtensionForMime, getFileIcon, isGoogleWorkspaceDoc, isRetryableError, loginWithBrowser, lookupMimeType, renderFileRow, runInteractiveExplorer, startWebDAVServer, terminalLink, withRetry };
package/dist/index.d.ts CHANGED
@@ -1,6 +1,8 @@
1
+ import * as http from 'http';
1
2
  import { drive_v3 } from '@googleapis/drive';
2
3
  import { OAuth2Client } from 'google-auth-library';
3
4
  import { EventEmitter } from 'node:events';
5
+ import http$1 from 'node:http';
4
6
 
5
7
  interface BrowserLoginOptions {
6
8
  clientId: string;
@@ -70,6 +72,10 @@ interface DriveKitOptions {
70
72
  enablePathCache?: boolean;
71
73
  /** Cache TTL in milliseconds (default: 5 minutes) */
72
74
  pathCacheTTL?: number;
75
+ /** Enable persistent SQLite metadata cache for 0ms path resolution across sessions (default: true) */
76
+ enablePersistentCache?: boolean;
77
+ /** Custom path to the SQLite cache database file (default: ~/.drivekit/cache.db) */
78
+ cacheDatabasePath?: string;
73
79
  /** Number of retry attempts for 429/5xx errors (default: 5) */
74
80
  maxRetries?: number;
75
81
  /** Base delay for exponential backoff in ms (default: 1000) */
@@ -126,6 +132,10 @@ interface UploadOptions {
126
132
  onProgress?: (progress: UploadProgress) => void;
127
133
  /** Whether to overwrite file with same name in destination */
128
134
  overwrite?: boolean;
135
+ /** Whether to enable instant upload deduplication by file MD5 hash */
136
+ deduplicate?: boolean;
137
+ /** Alias for target file name */
138
+ filename?: string;
129
139
  /** Custom properties / metadata */
130
140
  properties?: Record<string, string>;
131
141
  appProperties?: Record<string, string>;
@@ -255,6 +265,14 @@ declare class DriveQueryBuilder {
255
265
  * Custom raw query condition
256
266
  */
257
267
  raw(condition: string): this;
268
+ /**
269
+ * Custom raw query condition (alias for raw)
270
+ */
271
+ custom(condition: string): this;
272
+ /**
273
+ * Filter: Exact MD5 checksum match
274
+ */
275
+ md5(checksum: string): this;
258
276
  /**
259
277
  * Sort ordering (e.g. 'modifiedTime desc', 'name', 'folder,modifiedTime desc')
260
278
  */
@@ -275,6 +293,10 @@ declare class DriveQueryBuilder {
275
293
  * Executes query and returns array of matching files
276
294
  */
277
295
  list(): Promise<DriveApiFile[]>;
296
+ /**
297
+ * Executes query and returns array of matching files (alias for list)
298
+ */
299
+ execute(): Promise<DriveApiFile[]>;
278
300
  /**
279
301
  * Returns the first matching file, or null if not found
280
302
  */
@@ -449,6 +471,22 @@ declare class DriveFileRef {
449
471
  previewLink: string;
450
472
  directDownloadLink: string;
451
473
  }>;
474
+ /** Returns a ReadableStream for this file, optionally with byte Range requests */
475
+ createReadStream(options?: {
476
+ start?: number;
477
+ end?: number;
478
+ }): Promise<NodeJS.ReadableStream>;
479
+ /** Grants access to a specific email with custom role and notification */
480
+ grantAccess(options: {
481
+ email: string;
482
+ role?: 'reader' | 'commenter' | 'writer';
483
+ notify?: boolean;
484
+ message?: string;
485
+ }): Promise<DriveApiPermission>;
486
+ /** Revokes access by permission ID or user email */
487
+ revokeAccess(permissionIdOrEmail: string): Promise<void>;
488
+ /** Lists all granted permissions on this file */
489
+ listPermissions(): Promise<DriveApiPermission[]>;
452
490
  }
453
491
  /**
454
492
  * Fluent reference to a specific folder in Google Drive
@@ -469,6 +507,15 @@ declare class DriveFolderRef {
469
507
  pullTo(localDestinationDir: string, options?: Parameters<DriveKit['pull']>[2]): Promise<PullResult>;
470
508
  /** Watches this folder for real-time changes */
471
509
  watch(options?: Omit<WatcherOptions, 'folderId'>): Promise<DriveWatcher>;
510
+ /** Grants access to this entire folder */
511
+ grantAccess(options: {
512
+ email: string;
513
+ role?: 'reader' | 'commenter' | 'writer';
514
+ notify?: boolean;
515
+ message?: string;
516
+ }): Promise<DriveApiPermission>;
517
+ /** Creates a writable stream directly into a file inside this folder */
518
+ createWriteStream(fileName: string, options?: Omit<UploadOptions, 'source' | 'filename' | 'parent'>): Promise<NodeJS.WritableStream>;
472
519
  }
473
520
 
474
521
  interface DriveKitPlugin {
@@ -486,6 +533,106 @@ declare class PluginManager {
486
533
  runBeforeDownload(fileId: string, options: DownloadOptions): Promise<DownloadOptions>;
487
534
  runAfterDownload(result: any): Promise<any>;
488
535
  }
536
+ /**
537
+ * Creates an official Webhook Plugin to notify external services (Slack, Discord, Telegram, Zapier)
538
+ * when uploads or downloads finish.
539
+ */
540
+ declare function createWebhookPlugin(options: {
541
+ url: string;
542
+ headers?: Record<string, string>;
543
+ events?: ('upload' | 'download')[];
544
+ }): DriveKitPlugin;
545
+ /**
546
+ * Creates an Auto-Namer Plugin to automatically prefix/suffix or timestamp files
547
+ */
548
+ declare function createAutoNamePlugin(options: {
549
+ prefix?: string;
550
+ suffix?: string;
551
+ appendTimestamp?: boolean;
552
+ }): DriveKitPlugin;
553
+
554
+ interface CacheFileEntry {
555
+ id: string;
556
+ name: string;
557
+ mimeType: string;
558
+ size?: number;
559
+ parentId?: string;
560
+ path?: string;
561
+ md5Checksum?: string;
562
+ trashed: boolean;
563
+ modifiedTime?: string;
564
+ updatedAt?: number;
565
+ }
566
+ interface CacheStats {
567
+ fileCount: number;
568
+ folderCount: number;
569
+ totalSizeBytes: number;
570
+ lastSyncTime: string | null;
571
+ databasePath: string;
572
+ }
573
+ interface IMetadataCache {
574
+ init(): void;
575
+ getById(id: string): CacheFileEntry | null;
576
+ getByPath(normalizedPath: string): CacheFileEntry | null;
577
+ getChildren(parentId: string): CacheFileEntry[];
578
+ findByMd5(md5: string): CacheFileEntry | null;
579
+ searchByName(query: string): CacheFileEntry[];
580
+ upsertFile(entry: CacheFileEntry): void;
581
+ upsertFiles(entries: CacheFileEntry[]): void;
582
+ deleteFile(id: string): void;
583
+ clear(): void;
584
+ getMeta(key: string): string | null;
585
+ setMeta(key: string, value: string): void;
586
+ getStats(): CacheStats;
587
+ close(): void;
588
+ }
589
+ /**
590
+ * High-performance SQLite-backed persistent cache for DriveKit metadata.
591
+ * Uses Node 22's built-in `node:sqlite` (DatabaseSync).
592
+ */
593
+ declare class SqliteMetadataCache implements IMetadataCache {
594
+ private db;
595
+ private dbPath;
596
+ private initialized;
597
+ private fallbackMemory?;
598
+ constructor(customPath?: string);
599
+ init(): void;
600
+ getById(id: string): CacheFileEntry | null;
601
+ getByPath(normalizedPath: string): CacheFileEntry | null;
602
+ getChildren(parentId: string): CacheFileEntry[];
603
+ findByMd5(md5: string): CacheFileEntry | null;
604
+ searchByName(query: string): CacheFileEntry[];
605
+ upsertFile(entry: CacheFileEntry): void;
606
+ upsertFiles(entries: CacheFileEntry[]): void;
607
+ deleteFile(id: string): void;
608
+ clear(): void;
609
+ getMeta(key: string): string | null;
610
+ setMeta(key: string, value: string): void;
611
+ getStats(): CacheStats;
612
+ close(): void;
613
+ private mapRow;
614
+ }
615
+ /**
616
+ * Fallback in-memory cache if SQLite is unavailable
617
+ */
618
+ declare class MemoryMetadataCache implements IMetadataCache {
619
+ private files;
620
+ private meta;
621
+ init(): void;
622
+ getById(id: string): CacheFileEntry | null;
623
+ getByPath(normalizedPath: string): CacheFileEntry | null;
624
+ getChildren(parentId: string): CacheFileEntry[];
625
+ findByMd5(md5: string): CacheFileEntry | null;
626
+ searchByName(query: string): CacheFileEntry[];
627
+ upsertFile(entry: CacheFileEntry): void;
628
+ upsertFiles(entries: CacheFileEntry[]): void;
629
+ deleteFile(id: string): void;
630
+ clear(): void;
631
+ getMeta(key: string): string | null;
632
+ setMeta(key: string, value: string): void;
633
+ getStats(): CacheStats;
634
+ close(): void;
635
+ }
489
636
 
490
637
  declare class DriveKit {
491
638
  private options;
@@ -494,6 +641,7 @@ declare class DriveKit {
494
641
  private pathResolverInstance;
495
642
  private uploaderInstance;
496
643
  private downloaderInstance;
644
+ private metadataCacheInstance;
497
645
  private rootFolderId;
498
646
  private pluginManager;
499
647
  constructor(options?: DriveKitOptions);
@@ -682,6 +830,76 @@ declare class DriveKit {
682
830
  onFileStart?: (remoteName: string, relativePath: string) => void;
683
831
  onFileComplete?: (remoteName: string, localPath: string) => void;
684
832
  }): Promise<PullResult>;
833
+ /**
834
+ * Creates a readable stream for a file, supporting partial range requests
835
+ */
836
+ createReadStream(pathOrId: string, options?: {
837
+ start?: number;
838
+ end?: number;
839
+ }): Promise<NodeJS.ReadableStream>;
840
+ /**
841
+ * Creates a writable stream directly into Google Drive
842
+ */
843
+ createWriteStream(remotePath: string, options?: Omit<UploadOptions, 'source'>): Promise<NodeJS.WritableStream>;
844
+ /**
845
+ * Returns the active persistent metadata cache instance (SQLite/Memory)
846
+ */
847
+ getMetadataCache(): Promise<IMetadataCache | null>;
848
+ /**
849
+ * Returns cache statistics (total files, folders, size, last sync)
850
+ */
851
+ getCacheStats(): Promise<CacheStats | null>;
852
+ /**
853
+ * Clears the path and metadata cache
854
+ */
855
+ clearCache(): Promise<void>;
856
+ /**
857
+ * Crawls and indexes Google Drive metadata into the local SQLite database for instant 0ms lookups
858
+ */
859
+ syncCache(options?: {
860
+ onProgress?: (scanned: number) => void;
861
+ }): Promise<CacheStats>;
862
+ /**
863
+ * Lists all Google Workspace Shared Drives accessible by current user or service account
864
+ */
865
+ listSharedDrives(options?: {
866
+ pageSize?: number;
867
+ }): Promise<{
868
+ id: string;
869
+ name: string;
870
+ }[]>;
871
+ /**
872
+ * Creates a scoped DriveKit client locked to a specific Shared Drive
873
+ */
874
+ sharedDrive(driveId: string): DriveKit;
875
+ /**
876
+ * Grants access to a specific email with custom role and notification
877
+ */
878
+ grantAccess(pathOrId: string, options: {
879
+ email: string;
880
+ role?: 'reader' | 'commenter' | 'writer';
881
+ notify?: boolean;
882
+ message?: string;
883
+ }): Promise<DriveApiPermission>;
884
+ /**
885
+ * Revokes access for a specific permission ID or email address
886
+ */
887
+ revokeAccess(pathOrId: string, permissionIdOrEmail: string): Promise<void>;
888
+ /**
889
+ * Lists all active permissions on a file or folder
890
+ */
891
+ listPermissions(pathOrId: string): Promise<DriveApiPermission[]>;
892
+ /**
893
+ * Starts an embedded WebDAV server to mount DriveKit directly in macOS Finder or Windows Explorer
894
+ */
895
+ serveWebDAV(options?: {
896
+ port?: number;
897
+ host?: string;
898
+ }): Promise<{
899
+ server: http.Server;
900
+ url: string;
901
+ close: () => Promise<void>;
902
+ }>;
685
903
  /**
686
904
  * Calculates local file MD5 hash for integrity and deduplication checks
687
905
  */
@@ -774,9 +992,11 @@ declare class PathResolver {
774
992
  private cache;
775
993
  private cacheTTL;
776
994
  private enableCache;
995
+ private metadataCache?;
777
996
  constructor(drive: drive_v3.Drive, rootFolderId?: string, options?: {
778
997
  enableCache?: boolean;
779
998
  cacheTTL?: number;
999
+ metadataCache?: IMetadataCache;
780
1000
  });
781
1001
  /**
782
1002
  * Normalizes a virtual path (e.g. "///Backups//2026/" -> "/Backups/2026")
@@ -874,6 +1094,13 @@ declare class Downloader {
874
1094
  mimeType: string;
875
1095
  size?: number;
876
1096
  }>;
1097
+ /**
1098
+ * Returns a raw ReadableStream for the file, supporting HTTP Range requests for partial content / streaming.
1099
+ */
1100
+ createReadStream(fileId: string, options?: {
1101
+ start?: number;
1102
+ end?: number;
1103
+ }): Promise<NodeJS.ReadableStream>;
877
1104
  }
878
1105
 
879
1106
  /**
@@ -898,6 +1125,20 @@ declare class ConcurrencyPool {
898
1125
  map<Item, Result>(items: Item[], fn: (item: Item, index: number) => Promise<Result>): Promise<Result[]>;
899
1126
  }
900
1127
 
1128
+ interface WebDAVServerOptions {
1129
+ port?: number;
1130
+ host?: string;
1131
+ }
1132
+ /**
1133
+ * Creates and starts a lightweight zero-dependency WebDAV server for DriveKit.
1134
+ * Allows mounting Google Drive directly in macOS Finder, Windows Explorer, or Linux.
1135
+ */
1136
+ declare function startWebDAVServer(drive: DriveKit, options?: WebDAVServerOptions): Promise<{
1137
+ server: http$1.Server;
1138
+ url: string;
1139
+ close: () => Promise<void>;
1140
+ }>;
1141
+
901
1142
  /**
902
1143
  * Creates an OSC 8 clickable hyperlink in supported modern terminals (macOS Terminal, iTerm2, VS Code, etc.)
903
1144
  */
@@ -993,4 +1234,4 @@ declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Pro
993
1234
  */
994
1235
  declare function createDrive(options?: DriveKitOptions): Promise<DriveKit>;
995
1236
 
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 };
1237
+ export { type BrowserLoginOptions, type CacheFileEntry, type CacheStats, 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 IMetadataCache, type LoginResult, MIN_CHUNK_SIZE, MULTIPART_THRESHOLD, MemoryMetadataCache, PathResolver, type PermissionRole, type PermissionType, PluginManager, type PullResult, ResumableUploader, type RetryOptions, type ShareOptions, SmartSyncEngine, SqliteMetadataCache, StorageCleaner, type SyncResult, type UploadOptions, type UploadProgress, type WatcherOptions, type WebDAVServerOptions, calculateFileMd5, createAutoNamePlugin, createDrive, createWebhookPlugin, DriveKit as default, formatBytes, formatDuration, formatSpeed, getExtensionForMime, getFileIcon, isGoogleWorkspaceDoc, isRetryableError, loginWithBrowser, lookupMimeType, renderFileRow, runInteractiveExplorer, startWebDAVServer, terminalLink, withRetry };