drivekit 0.0.0-stage → 1.0.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/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Moaaz
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
package/README.ar.md ADDED
@@ -0,0 +1,243 @@
1
+ # ⚡ DriveKit (أداة Google Drive فائقة السرعة والمرونة للمطورين)
2
+
3
+ > حزمة جافاسكريبت وتايب سكريبت حديثة، فائقة السرعة والموثوقية، تمنح المطورين قوة مطلقة في التعامل مع **Google Drive** بأبسط كود ممكن وبأعلى أداء!
4
+
5
+ ---
6
+
7
+ ## 🌟 لماذا DriveKit؟
8
+
9
+ التعامل المباشر مع مكتبات Google Drive الرسمية مليء بالتعقيدات:
10
+ - ❌ لا يوجد نظام مسارات حقيقي (تحتاج يدوياً للبحث عن معرف المجلد `folderId` خطوة بخطوة).
11
+ - ❌ رفع الملفات الكبيرة يتطلب كتابة مئات أسطر الكود للتعامل مع الرفع المتقطع والقطع وحسابات البايتات.
12
+ - ❌ مواجهة مشاكل تجاوز كوتا الاستعلامات (429 Rate Limits) وتوقف العمليات.
13
+ - ❌ كتابة استعلامات البحث كسلاسل نصية SQL معقدة ومعرضة للأخطاء الإملائية والهروب (Escaping).
14
+ - ❌ صعوبة تنزيل وتصدير مستندات Google Docs و Sheets و Slides إلى PDF أو Excel.
15
+
16
+ **DriveKit تحل كل هذه المشاكل بأسلوب ساحر!**
17
+
18
+ ---
19
+
20
+ ## ✨ المميزات الرئيسية
21
+
22
+ 1. 📂 **نظام مسارات افتراضي ذكي (Virtual Path System)**:
23
+ - تعامل مع Google Drive كنظام ملفات حقيقي: `drive.mkdirp('/Backups/2026')` أو الرفع المباشر إلى مسار: `parent: '/Projects/App'`.
24
+ - تخزين مؤقت تلقائي لمسارات المجلدات لتسريع العمليات وتوفير استعلامات الـ API.
25
+
26
+ 2. 🚀 **محرك رفع متقطع فائق السرعة (Resumable Chunked Uploader)**:
27
+ - رفع آمن للملفات الضخمة (ميجابايتات وجيجابايتات) بقطع سريعة (8MB أو 16MB).
28
+ - استئناف تلقائي عند انقطاع الشبكة بدون إعادة رفع الملف من الصفر.
29
+ - تتبع حي ودقيق: **نسبة الإنجاز %**، **سرعة الرفع الحالية (MB/s)**، **الوقت المتبقي المقدر (ETA)**.
30
+
31
+ 3. 🔍 **باني استعلامات سلس (Fluent Query Builder)**:
32
+ - كتابة استعلامات نظيفة وسلسة وسهلة القراءة بأسلوب السلسلة (Chaining).
33
+
34
+ 4. 🛡️ **مقاومة أخطاء الشبكة والكوتا (Exponential Backoff with Full Jitter)**:
35
+ - إعادة محاولة ذكية وتلقائية عند مواجهة `429 Too Many Requests` أو `5xx Backend Errors`.
36
+
37
+ 5. ⚡ **مزامنة المجلدات بالتوازي (Parallel Sync Engine)**:
38
+ - رفع مجلدات كاملة بجميع تفرعاتها بالتوازي مع التحكم في عدد المسارات المتزامنة (Concurrency).
39
+
40
+ 6. 📄 **تصدير مستندات Google تلقائياً**:
41
+ - تحويل Google Docs إلى PDF أو Docx، و Sheets إلى Excel أو CSV، و Slides إلى PDF بلمسة واحدة.
42
+
43
+ 7. 🔗 **مشاركة فورية للملفات**:
44
+ - تحويل أي ملف إلى عام بلمسة واحدة والحصول على رابط العرض والرابط المباشر للتحميل (`directDownloadLink`).
45
+
46
+ 8. 💻 **أداة سطر أوامر مدمجة (CLI)**:
47
+ - تشغيل مباشر من الطرفية عبر `drivekit ls` أو `drivekit upload` أو `drivekit sync`.
48
+
49
+ ---
50
+
51
+ ## 📦 التثبيت
52
+
53
+ ```bash
54
+ npm install drivekit
55
+ # أو
56
+ pnpm add drivekit
57
+ # أو
58
+ yarn add drivekit
59
+ ```
60
+
61
+ ---
62
+
63
+ ## 🔑 خيارات المصادقة السريعة
64
+
65
+ يدعم **DriveKit** كافة طرق المصادقة الشائعة:
66
+
67
+ ### 1. عبر ملف Service Account (الأكثر شيوعاً للمخدمات والبوتات):
68
+ ```typescript
69
+ import { createDrive } from 'drivekit';
70
+
71
+ const drive = await createDrive({
72
+ auth: {
73
+ keyFilePath: './service-account.json', // أو عبر متغير البيئة GOOGLE_APPLICATION_CREDENTIALS
74
+ },
75
+ });
76
+ ```
77
+
78
+ ### 2. عبر رمز الدخول المباشر (Access Token):
79
+ ```typescript
80
+ const drive = await createDrive({
81
+ auth: { accessToken: 'ya29.a0AfH...' }
82
+ });
83
+ ```
84
+
85
+ ### 3. عبر OAuth2:
86
+ ```typescript
87
+ const drive = await createDrive({
88
+ auth: {
89
+ oauth: {
90
+ clientId: 'YOUR_CLIENT_ID',
91
+ clientSecret: 'YOUR_CLIENT_SECRET',
92
+ refreshToken: 'YOUR_REFRESH_TOKEN',
93
+ }
94
+ }
95
+ });
96
+ ```
97
+
98
+ ---
99
+
100
+ ## 🚀 أمثلة عملية
101
+
102
+ ### 1. رفع ملف مع تتبع السرعة ونسبة الإنجاز
103
+ ```typescript
104
+ const file = await drive.upload({
105
+ source: './database-backup.zip', // مسار ملف محلي أو Buffer أو Stream
106
+ name: 'db-backup-2026.zip',
107
+ parent: '/Backups/Databases', // مسار افتراضي (يتم إنشاؤه تلقائياً إن لم يوجد!)
108
+ overwrite: true,
109
+ onProgress: (p) => {
110
+ console.log(`نسبة الإنجاز: ${p.percentage}% | السرعة: ${p.speedFormatted} | متبقي: ${p.estimatedTimeRemainingSeconds} ثانية`);
111
+ },
112
+ });
113
+
114
+ console.log(`تم الرفع بنجاح! معرف الملف: ${file.id}`);
115
+ ```
116
+
117
+ ### 2. البحث والاستعلام بأسلوب سلس (Query Builder)
118
+ ```typescript
119
+ const files = await drive.query()
120
+ .nameContains('invoice')
121
+ .mimeType('application/pdf')
122
+ .notTrashed()
123
+ .modifiedAfter('2026-01-01')
124
+ .orderBy('modifiedTime desc')
125
+ .pageSize(20)
126
+ .list();
127
+
128
+ for (const f of files) {
129
+ console.log(`- ${f.name} [${f.id}]`);
130
+ }
131
+ ```
132
+
133
+ ### 3. تنزيل ملف أو تصدير مستند
134
+ ```typescript
135
+ // تنزيل ملف وحفظه في مجلد محلي
136
+ await drive.download('FILE_ID_OR_PATH', {
137
+ destination: './downloads',
138
+ onProgress: (p) => {
139
+ console.log(`تم تنزيل: ${p.bytesRead} بايت بسرعه ${p.speedFormatted}`);
140
+ }
141
+ });
142
+ ```
143
+
144
+ ### 4. قراءة محتوى نصي أو JSON مباشرة
145
+ ```typescript
146
+ // قراءة ملف JSON من الدرايف مباشرة
147
+ const config = await drive.getJson('/Config/settings.json');
148
+ console.log(config);
149
+
150
+ // قراءة نص
151
+ const text = await drive.getText('/Notes/todo.txt');
152
+ ```
153
+
154
+ ### 5. مشاركة الملف والحصول على الروابط
155
+ ```typescript
156
+ // جعل الملف متاحاً لأي شخص لديه الرابط والحصول على رابط مباشر
157
+ const links = await drive.sharePublic('FILE_ID_OR_PATH');
158
+ console.log('رابط المعاينة:', links.previewLink);
159
+ console.log('رابط التحميل المباشر:', links.directDownloadLink);
160
+
161
+ // أو مشاركته مع بريد محدد
162
+ await drive.share('FILE_ID', {
163
+ role: 'writer',
164
+ emailAddress: 'colleague@example.com',
165
+ sendNotificationEmail: true,
166
+ });
167
+ ```
168
+
169
+ ### 6. مزامنة مجلد كامل بالتوازي (Folder Sync)
170
+ ```typescript
171
+ const result = await drive.syncFolder('./my-project-build', '/Builds/Release-v1', {
172
+ concurrency: 5, // رفع 5 ملفات بالتوازي
173
+ overwrite: true,
174
+ onFileComplete: (path, id) => {
175
+ console.log(`تم رفع: ${path}`);
176
+ }
177
+ });
178
+
179
+ console.log(`تمت مزامنة ${result.uploaded.length} ملف بنجاح في ${result.durationMs / 1000} ثانية!`);
180
+ ```
181
+
182
+ ---
183
+
184
+ ## 💻 استخدام أداة سطر الأوامر (CLI)
185
+
186
+ يمكنك استخدام الأداة مباشرة من الطرفية:
187
+
188
+ ```bash
189
+ # عرض المساحة التخزينية والكوتا
190
+ npx drivekit quota -k ./service-account.json
191
+
192
+ # استعراض المجلدات
193
+ npx drivekit ls /Backups -k ./service-account.json
194
+
195
+ # رفع ملف مع شريط تقدم حي وحساب السرعة
196
+ npx drivekit upload ./video.mp4 /Videos -k ./service-account.json
197
+
198
+ # تنزيل ملف
199
+ npx drivekit download FILE_ID ./destination -k ./service-account.json
200
+
201
+ # مشاركة ملف وجعله عاماً
202
+ npx drivekit share FILE_ID -k ./service-account.json
203
+
204
+ # مزامنة مجلد كامل تفرعياً
205
+ npx drivekit sync ./dist /Websites/Production -c 6 -k ./service-account.json
206
+ ```
207
+
208
+ > **ملاحظة**: إذا قمت بضبط متغير البيئة `export GOOGLE_APPLICATION_CREDENTIALS="./service-account.json"`، فلن تحتاج لتمرير خيار `-k` في كل مرة!
209
+
210
+ ---
211
+
212
+ ## 📚 موقع التوثيق الرسمي (VitePress)
213
+
214
+ تم بناء موقع توثيق تفاعلي كامل ومزدوج اللغة (عربي / إنجليزي) عبر **VitePress**:
215
+
216
+ ```bash
217
+ # تشغيل موقع التوثيق محلياً (وضع التطوير)
218
+ npm run docs:dev
219
+
220
+ # بناء نسخة الإنتاج لموقع التوثيق
221
+ npm run docs:build
222
+
223
+ # معاينة النسخة المبنية
224
+ npm run docs:preview
225
+ ```
226
+
227
+ ---
228
+
229
+ ## 🧪 الاختبارات والبناء
230
+
231
+ ```bash
232
+ # تشغيل جميع الاختبارات
233
+ npm test
234
+
235
+ # فحص الأنواع وبناء الحزمة
236
+ npm run build
237
+ ```
238
+
239
+ ---
240
+
241
+ ## 📄 الترخيص
242
+ MIT License - متاح للاستخدام التجاري والشخصي بحرية تامة.
243
+
package/README.md CHANGED
@@ -1,3 +1,198 @@
1
- # Temporary Holding Version
1
+ # ⚡ DriveKit
2
+
3
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4
+ [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
5
+ [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green.svg)](https://nodejs.org/)
6
+
7
+ > **DriveKit** is a fast, powerful, and developer-friendly Google Drive SDK and CLI for JavaScript and TypeScript.
8
+
9
+ ---
10
+
11
+ ## 🚀 Why DriveKit?
12
+
13
+ Working with the raw Google Drive API is often tedious:
14
+ - **No virtual path system**: You must resolve folder IDs manually layer-by-layer.
15
+ - **Resumable uploads are difficult**: Handling chunked uploads, resume checkpoints, and network backoff requires hundreds of lines of boilerplate.
16
+ - **Strict rate limits**: Hitting `429 Too Many Requests` or `503 Service Unavailable` crashes unhandled pipelines.
17
+ - **Search syntax is cryptic**: String interpolation with SQL-like syntax (`'root' in parents and trashed = false`) is prone to formatting bugs.
18
+ - **Exporting Google Docs/Sheets is clunky**: Binary downloads fail if a file is a Google Doc or Sheet unless converted.
19
+
20
+ **DriveKit solves all of this with an intuitive, production-ready API.**
21
+
22
+ ---
23
+
24
+ ## 🌟 Key Features
25
+
26
+ - 📂 **Virtual Filesystem Paths**: Treat Drive like a filesystem (`/Backups/2026/DB.dump`). Auto-creates missing parents (`mkdirp`).
27
+ - ⚡ **High-Speed Resumable Uploader**:
28
+ - Memory-efficient chunked uploads (configurable 8MB or 16MB chunk sizes).
29
+ - Auto-resumes from interrupted byte offset.
30
+ - Real-time metrics: **Percentage (%)**, **Live Speed (MB/s)**, and **ETA**.
31
+ - 🔍 **Fluent Query Builder**: Chainable methods (`.nameContains()`, `.mimeType()`, `.notTrashed()`, `.orderBy()`, `.pageSize()`).
32
+ - 🛡️ **Adaptive Rate Limiting & Backoff**: Exponential backoff with full jitter automatically catches and retries `429` and `5xx` errors.
33
+ - 🔄 **Parallel Directory Sync**: Concurrently sync entire local folder trees with configurable concurrency limit.
34
+ - 📑 **Auto-Export Google Docs**: Seamlessly exports Google Docs (PDF/Docx), Sheets (Excel/CSV), and Slides (PDF).
35
+ - 🔗 **Instant Sharing**: One-liner to make files publicly accessible and obtain direct download and preview URLs.
36
+ - 💻 **Modern CLI Included**: Perform operations right from your terminal with `drivekit ls`, `drivekit upload`, `drivekit sync`, etc.
37
+
38
+ ---
39
+
40
+ ## 📦 Installation
41
+
42
+ ```bash
43
+ npm install drivekit
44
+ # or
45
+ pnpm add drivekit
46
+ # or
47
+ yarn add drivekit
48
+ ```
49
+
50
+ ---
51
+
52
+ ## 🔑 Authentication
53
+
54
+ DriveKit supports all standard authentication strategies:
55
+
56
+ ```typescript
57
+ import { createDrive } from 'drivekit';
58
+
59
+ // 1. Service Account JSON file (or GOOGLE_APPLICATION_CREDENTIALS)
60
+ const drive = await createDrive({
61
+ auth: { keyFilePath: './service-account.json' },
62
+ });
63
+
64
+ // 2. Direct Bearer Access Token
65
+ const drive = await createDrive({
66
+ auth: { accessToken: 'ya29.a0AfH...' },
67
+ });
68
+
69
+ // 3. OAuth2 Client Credentials & Refresh Token
70
+ const drive = await createDrive({
71
+ auth: {
72
+ oauth: {
73
+ clientId: 'YOUR_CLIENT_ID',
74
+ clientSecret: 'YOUR_CLIENT_SECRET',
75
+ refreshToken: 'YOUR_REFRESH_TOKEN',
76
+ },
77
+ },
78
+ });
79
+ ```
80
+
81
+ ---
82
+
83
+ ## 💡 Quick Examples
84
+
85
+ ### Uploading a Large File with Live Progress
86
+ ```typescript
87
+ const file = await drive.upload({
88
+ source: './large-archive.tar.gz',
89
+ name: 'backup.tar.gz',
90
+ parent: '/Backups/Servers', // Automatically creates folders if missing!
91
+ overwrite: true,
92
+ onProgress: (p) => {
93
+ console.log(`${p.percentage}% | ${p.speedFormatted} | ETA: ${p.estimatedTimeRemainingSeconds}s`);
94
+ },
95
+ });
96
+ ```
97
+
98
+ ### Fluent Search Query
99
+ ```typescript
100
+ const files = await drive.query()
101
+ .nameContains('invoice')
102
+ .mimeType('application/pdf')
103
+ .notTrashed()
104
+ .modifiedAfter('2026-01-01')
105
+ .orderBy('modifiedTime desc')
106
+ .list();
107
+ ```
108
+
109
+ ### Downloading or Exporting
110
+ ```typescript
111
+ await drive.download('/Documents/Report.docx', {
112
+ destination: './local-folder',
113
+ onProgress: (p) => {
114
+ console.log(`Downloaded ${p.bytesRead} bytes at ${p.speedFormatted}`);
115
+ },
116
+ });
117
+ ```
118
+
119
+ ### Read JSON or Text Directly
120
+ ```typescript
121
+ const config = await drive.getJson('/Config/settings.json');
122
+ const text = await drive.getText('/Notes/todo.txt');
123
+ ```
124
+
125
+ ### Public Sharing
126
+ ```typescript
127
+ const links = await drive.sharePublic(file.id);
128
+ console.log('Preview:', links.previewLink);
129
+ console.log('Direct Download:', links.directDownloadLink);
130
+ ```
131
+
132
+ ### Concurrent Folder Sync
133
+ ```typescript
134
+ const result = await drive.syncFolder('./dist', '/Websites/Production', {
135
+ concurrency: 6, // 6 parallel uploads
136
+ overwrite: true,
137
+ });
138
+ console.log(`Synced ${result.uploaded.length} files in ${result.durationMs / 1000}s`);
139
+ ```
140
+
141
+ ---
142
+
143
+ ## 💻 CLI Usage
144
+
145
+ ```bash
146
+ # Set credentials once
147
+ export GOOGLE_APPLICATION_CREDENTIALS="./service-account.json"
148
+
149
+ # Check quota
150
+ npx drivekit quota
151
+
152
+ # List folder contents
153
+ npx drivekit ls /Backups
154
+
155
+ # Upload with progress
156
+ npx drivekit upload ./archive.zip /Backups
157
+
158
+ # Download
159
+ npx drivekit download FILE_ID ./downloads
160
+
161
+ # Share
162
+ npx drivekit share FILE_ID
163
+
164
+ # Recursive sync
165
+ npx drivekit sync ./dist /Backups -c 4
166
+ ```
167
+
168
+ ---
169
+
170
+ ## 📚 Interactive Documentation (VitePress)
171
+
172
+ DriveKit includes a bilingual (Arabic & English) interactive documentation site built with **VitePress**:
173
+
174
+ ```bash
175
+ # Start local documentation dev server
176
+ npm run docs:dev
177
+
178
+ # Build static documentation site
179
+ npm run docs:build
180
+
181
+ # Preview production build
182
+ npm run docs:preview
183
+ ```
184
+
185
+ ---
186
+
187
+ ## 🧪 Testing
188
+
189
+ ```bash
190
+ npm test
191
+ npm run build
192
+ ```
193
+
194
+ ---
195
+
196
+ ## 📄 License
197
+ MIT © Moaaz
2
198
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
@@ -0,0 +1,13 @@
1
+ #!/usr/bin/env node
2
+
3
+ import('../dist/cli.js')
4
+ .then((m) => {
5
+ if (m.runCLI) {
6
+ m.runCLI();
7
+ }
8
+ })
9
+ .catch((err) => {
10
+ console.error('DriveKit CLI Error:', err);
11
+ process.exit(1);
12
+ });
13
+