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/cli.cjs +1082 -29
- package/dist/cli.cjs.map +1 -1
- package/dist/cli.js +1086 -28
- package/dist/cli.js.map +1 -1
- package/dist/index.cjs +1085 -20
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +242 -1
- package/dist/index.d.ts +242 -1
- package/dist/index.js +1104 -28
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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 };
|