@vqh2602/mini-app-sdk 1.0.0 → 1.0.1

package/README.md

@@ -1,58 +1,160 @@
-# @vqh2602/mini-app-sdk
+# SuperApp Mini App Developer SDK Ecosystem
 
-Bộ TypeScript SDK chính thức dành cho các nhà phát triển thứ ba xây dựng ứng dụng nhỏ (Mini App) trên nền tảng SuperApp.
+Hệ sinh thái bộ công cụ SDK, Bridge Transport, Mock Engine, CLI và Browser Simulator dành riêng cho các nhà phát triển thứ ba (3rd-party developers) xây dựng, kiểm thử và xuất bản Mini App trên nền tảng SuperApp.
 
-## 🚀 Tính năng nổi bật
+---
 
-- **100% TypeScript**: Định kiểu rõ ràng, tự động gợi ý code (IntelliSense) cho mọi hàm và tham số.
-- **Tự động chuyển đổi môi trường**: Chạy mượt mà trên cả Flutter WebView thật, trong iframe Browser Simulator, hay độc lập (Mock Engine tự động).
-- **Hỗ trợ đầy đủ nghiệp vụ SuperApp**:
-  - `auth`: Đăng nhập, cấp quyền OAuth, lấy User Profile, quản lý token.
-  - `payment`: Tích hợp thanh toán trực tiếp qua ví SuperApp.
-  - `device`: Pin, thông tin mạng, rung xúc giác haptic feedback, thông số màn hình.
-  - `storage`: Lưu trữ key-value cách ly và an toàn theo từng Mini App.
-  - `ui`: Toast thông báo, Alert, Confirm, đổi tiêu đề thanh điều hướng.
-  - `media`: Quét QR code camera, chọn ảnh.
-  - `lifecycle`: Bắt sự kiện app vào nền (Background) hoặc ra màn hình (Foreground).
+## 🏗️ 1. Kiến Trúc Hợp Nhất (All-in-One Package: `@vqh2602/mini-app-sdk`)
 
-## 📦 Cài đặt
+Toàn bộ hệ thống SDK, Mock Engine, Bridge Transport, CLI và Browser Simulator đã được hợp nhất vào **1 gói npm duy nhất**:
 
+| Khối chức năng | Thư mục source | Vai trò & Trách nhiệm |
+| :--- | :--- | :--- |
+| **Mini App Core SDK** | `src/core/` | Bộ API chính thức cho bên thứ ba (`npm install @vqh2602/mini-app-sdk`): `auth`, `payment`, `device`, `storage`, `ui`, `media`, `lifecycle`. |
+| **Bridge Transport** | `src/transport/` | Lớp trừu tượng hoá Bridge: chuyển đổi linh hoạt giữa Flutter WebView Native (`FlutterBridge`), PostMessage trong iframe Simulator, hoặc Mock cục bộ. |
+| **SDK Mock Engine** | `src/mock/` | Động cơ giả lập Native: sinh mã `authCode`, cấp `accessToken`, hồ sơ người dùng, quản lý số dư ví, trừ tiền thanh toán, giả lập pin, mạng, độ trễ và lưu trữ cách ly. |
+| **Mini App CLI** | `src/cli/` & `bin/` | Công cụ dòng lệnh: `create` (tạo dự án mẫu), `dev` (khởi chạy dev server + simulator), `build` (biên dịch + checksum), `upload` (gửi lên Registry), `simulator`. |
+| **Browser Simulator** | `simulator/` & `simulator-dist/` | Giao diện web giả lập điện thoại đã được build sẵn tĩnh, tích hợp trực tiếp vào lệnh `miniapp dev` và `miniapp simulator`. |
+
+---
+
+## ⚡ 2. Hướng Dẫn Vận Hành Cho Nhà Phát Triển (Quickstart)
+
+### Bước 1: Khởi tạo Mini App mới bằng CLI
+Lập trình viên bên thứ ba có thể chạy trực tiếp thông qua `npx`:
+```bash
+npx @vqh2602/mini-app-sdk create my_awesome_app
+```
+Hoặc nếu đã cài đặt toàn cục (`npm install -g @vqh2602/mini-app-sdk`):
+```bash
+miniapp create my_awesome_app
+```
+Lệnh này sẽ tự động sinh:
+- `app.json`: Manifest khai báo `appId`, `name`, `version`, `permissions`, `themeColor`.
+- `package.json`: Cài đặt sẵn `@vqh2602/mini-app-sdk`.
+- `src/main.ts`: Code mẫu gọi các hàm đăng nhập, thanh toán, pin, toast.
+- `index.html` & `vite.config.ts`.
+
+### Bước 2: Chạy Dev Server & Browser Simulator đồng thời
+```bash
+cd my_awesome_app
+npx miniapp dev
+```
+Lệnh `miniapp dev` sẽ khởi chạy cả:
+* Vite dev server của Mini App (Port 3000)
+* Browser Simulator tích hợp sẵn (Port 5175 tại `http://localhost:5175/?url=http://localhost:3000`)
+
+### Bước 3: Đóng gói và xuất bản Mini App
 ```bash
-npm install @vqh2602/mini-app-sdk
+# Đóng gói và kiểm tra checksum
+npx miniapp build
+
+# Tải lên SuperApp Dynamic Registry và gửi xét duyệt
+npx miniapp upload --submit --notes "Phát hành phiên bản 1.0.0"
 ```
 
-## 💡 Hướng dẫn nhanh (Quickstart)
+---
+
+## 📖 3. Bảng Tra Cứu API Mini App SDK (`@vqh2602/mini-app-sdk`)
 
+### 🔐 3.1. Xác thực & Người dùng (`superApp.auth`)
 ```typescript
 import superApp from '@vqh2602/mini-app-sdk';
 
-// 1. Đăng nhập người dùng
-const authData = await superApp.auth.login({
+// Đăng nhập và xin cấp quyền profile + phone
+const loginRes = await superApp.auth.login({
   scopes: ['user.profile', 'user.phone'],
 });
-console.log('Xin chào:', authData.user.name);
+console.log('User Name:', loginRes.user.name);
+console.log('Access Token:', loginRes.accessToken);
+
+// Lấy thông tin người dùng hiện tại
+const profile = await superApp.auth.getUserProfile();
+
+// Lấy Access Token
+const token = await superApp.auth.getAccessToken();
 
-// 2. Gọi thanh toán đơn hàng
+// Đăng xuất
+await superApp.auth.logout();
+```
+
+### 💳 3.2. Thanh toán SuperApp Pay (`superApp.payment`)
+```typescript
 try {
   const result = await superApp.payment.requestPayment({
-    orderId: 'ORDER_12345',
-    amount: 50000,
-    description: 'Thanh toán cà phê sữa đá',
+    orderId: 'ORDER_2026_001',
+    amount: 150000,
+    description: 'Thanh toán Combo Cơm Trưa',
   });
   
   if (result.status === 'SUCCESS') {
-    await superApp.ui.showToast('Thanh toán thành công!');
+    await superApp.ui.showToast('Thanh toán thành công qua Ví SuperApp!');
+  }
+} catch (error: any) {
+  if (error.code === 'INSUFFICIENT_FUNDS') {
+    await superApp.ui.showAlert({ title: 'Lỗi', message: 'Số dư ví không đủ' });
+  } else if (error.code === 'USER_CANCELLED') {
+    await superApp.ui.showToast('Bạn đã huỷ thanh toán');
   }
-} catch (error) {
-  await superApp.ui.showToast('Giao dịch thất bại');
 }
+```
 
-// 3. Đọc ghi bộ nhớ cục bộ
-await superApp.storage.setItem('user_cart', { items: 2, total: 50000 });
+### 📱 3.3. Thiết bị & Phần cứng (`superApp.device`)
+```typescript
+// Mức pin và trạng thái sạc
+const battery = await superApp.device.getBatteryInfo();
+console.log(`Pin: ${battery.batteryLevel}%, Đang sạc: ${battery.isCharging}`);
+
+// Trạng thái mạng
+const network = await superApp.device.getNetworkInfo();
+console.log(`Kết nối: ${network.networkType}, WiFi: ${network.isWifi}`);
+
+// Rung xúc giác haptic feedback
+await superApp.device.vibrate('light'); // 'light' | 'medium' | 'heavy'
+```
+
+### 💾 3.4. Lưu trữ cách ly (`superApp.storage`)
+```typescript
+// Ghi dữ liệu
+await superApp.storage.setItem('user_cart', { items: [{ id: 1, name: 'Trà Sữa' }] });
+
+// Đọc dữ liệu (Tự động deserialize JSON)
 const cart = await superApp.storage.getItem('user_cart');
 
-// 4. Lắng nghe trạng thái ứng dụng
+// Xoá key
+await superApp.storage.removeItem('user_cart');
+```
+
+### 🔔 3.5. Giao diện & Điều hướng (`superApp.ui` / `superApp.navigation`)
+```typescript
+// Toast
+await superApp.ui.showToast('Cập nhật thành công!');
+
+// Alert Dialog
+await superApp.ui.showAlert({ title: 'Chúc mừng', message: 'Nhận được voucher 50%' });
+
+// Confirm Dialog
+const agreed = await superApp.ui.showConfirm({
+  title: 'Xoá giỏ hàng',
+  message: 'Bạn có chắc chắn muốn làm trống giỏ hàng?',
+});
+
+// Đặt tiêu đề thanh điều hướng
+await superApp.ui.setNavigationBarTitle('Menu Quán Cà Phê');
+
+// Đóng Mini App về màn hình chính SuperApp
+await superApp.closeApp();
+```
+
+### 🔄 3.6. Vòng đời ứng dụng (`superApp.lifecycle`)
+```typescript
+// Bắt sự kiện khi app ra màn hình (Foreground)
 superApp.lifecycle.onAppShow(() => {
   console.log('Mini App hiển thị trở lại');
 });
+
+// Bắt sự kiện khi app bị ẩn xuống nền (Background)
+superApp.lifecycle.onAppHide(() => {
+  console.log('Mini App tạm dừng');
+});
 ```

package/bin/miniapp.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import('../dist/cli/index.js').catch((err) => {
+  console.error('[miniapp fatal error]', err);
+  process.exit(1);
+});

package/bin/simulator.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+let distDir = path.resolve(__dirname, '../simulator-dist');
+if (!fs.existsSync(distDir)) {
+  distDir = path.resolve(__dirname, '../dist/simulator');
+}
+
+const args = process.argv.slice(2);
+const portIndex = args.indexOf('--port');
+const port = portIndex !== -1 && args[portIndex + 1] ? parseInt(args[portIndex + 1], 10) : 5175;
+
+const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff2': 'font/woff2',
+};
+
+const server = http.createServer((req, res) => {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, HEAD, OPTIONS');
+
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  const parsedUrl = new URL(req.url, `http://localhost:${port}`);
+  let pathname = parsedUrl.pathname;
+  let filePath = path.join(distDir, pathname);
+
+  if (!filePath.startsWith(distDir)) {
+    res.writeHead(403);
+    res.end('Forbidden');
+    return;
+  }
+
+  fs.stat(filePath, (err, stats) => {
+    if (err || !stats.isFile()) {
+      filePath = path.join(distDir, 'index.html');
+    }
+
+    const ext = path.extname(filePath).toLowerCase();
+    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+
+    fs.readFile(filePath, (readErr, data) => {
+      if (readErr) {
+        res.writeHead(404);
+        res.end('Not Found');
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': contentType });
+      res.end(data);
+    });
+  });
+});
+
+server.listen(port, () => {
+  console.log(`\n📱 \x1b[36mSuperApp Browser Simulator\x1b[0m is running at: \x1b[1mhttp://localhost:${port}\x1b[0m`);
+  console.log(`🔗 Open with target Mini App: \x1b[32mhttp://localhost:${port}/?url=http://localhost:3000\x1b[0m\n`);
+});

package/dist/cli/commands/build.d.ts

@@ -0,0 +1,5 @@
+export interface BuildCommandOptions {
+    outDir?: string;
+}
+export declare function buildProject(options?: BuildCommandOptions): Promise<void>;
+//# sourceMappingURL=build.d.ts.map

package/dist/cli/commands/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/build.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgEnF"}

package/dist/cli/commands/build.js

@@ -0,0 +1,65 @@
+import { execSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadManifest } from '../utils/config.js';
+import { logger } from '../utils/logger.js';
+export async function buildProject(options = {}) {
+    const manifest = loadManifest();
+    const outDir = options.outDir || 'dist';
+    logger.title(`Đóng gói Mini App: ${manifest.name} (v${manifest.version})`);
+    logger.step(1, 3, 'Xác thực cấu hình app.json và các quyền permissions...');
+    if (manifest.permissions) {
+        logger.info(`Permissions: ${manifest.permissions.join(', ')}`);
+    }
+    logger.step(2, 3, 'Biên dịch mã nguồn với Vite & TypeScript...');
+    try {
+        execSync('npx vite build', { stdio: 'inherit' });
+    }
+    catch (err) {
+        logger.error('Lỗi khi biên dịch mã nguồn Mini App', err);
+        process.exit(1);
+    }
+    const distPath = path.resolve(process.cwd(), outDir);
+    const indexPath = path.join(distPath, manifest.entry || 'index.html');
+    if (!fs.existsSync(indexPath)) {
+        logger.error(`Không tìm thấy file entry "${manifest.entry}" trong thư mục build: ${distPath}`);
+        process.exit(1);
+    }
+    logger.step(3, 3, 'Tính toán checksum và tạo metadata gói phát hành...');
+    // Compute checksum of dist files
+    const hash = crypto.createHash('sha256');
+    function hashDirectory(dir) {
+        const files = fs.readdirSync(dir);
+        for (const file of files) {
+            const fullPath = path.join(dir, file);
+            const stat = fs.statSync(fullPath);
+            if (stat.isDirectory()) {
+                hashDirectory(fullPath);
+            }
+            else {
+                hash.update(fs.readFileSync(fullPath));
+            }
+        }
+    }
+    hashDirectory(distPath);
+    const bundleChecksum = hash.digest('hex');
+    const bundleMeta = {
+        appId: manifest.appId,
+        name: manifest.name,
+        version: manifest.version,
+        description: manifest.description,
+        entry: manifest.entry,
+        category: manifest.category,
+        themeColor: manifest.themeColor,
+        permissions: manifest.permissions,
+        checksum: bundleChecksum,
+        builtAt: new Date().toISOString(),
+    };
+    fs.writeFileSync(path.join(distPath, 'bundle-meta.json'), JSON.stringify(bundleMeta, null, 2));
+    logger.success(`Đóng gói thành công gói phát hành Mini App!`);
+    logger.info(`Thư mục output: ${distPath}`);
+    logger.info(`Bundle SHA256: ${bundleChecksum}`);
+    console.log(`\nSẵn sàng tải lên với lệnh:\n  npx miniapp upload\n`);
+}
+//# sourceMappingURL=build.js.map

package/dist/cli/commands/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../src/cli/commands/build.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/create.d.ts

@@ -0,0 +1,5 @@
+export interface CreateCommandOptions {
+    template?: string;
+}
+export declare function createProject(projectName: string, options?: CreateCommandOptions): Promise<void>;
+//# sourceMappingURL=create.d.ts.map

package/dist/cli/commands/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/create.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmO1G"}

package/dist/cli/commands/create.js

@@ -0,0 +1,220 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from '../utils/logger.js';
+export async function createProject(projectName, options = {}) {
+    const targetDir = path.resolve(process.cwd(), projectName);
+    if (fs.existsSync(targetDir)) {
+        logger.error(`Thư mục "${projectName}" đã tồn tại. Vui lòng chọn tên khác hoặc xoá thư mục cũ.`);
+        process.exit(1);
+    }
+    logger.title(`Khởi tạo Mini App mới: ${projectName}`);
+    logger.step(1, 3, `Đang tạo cấu trúc thư mục tại: ${targetDir}`);
+    fs.mkdirSync(targetDir, { recursive: true });
+    fs.mkdirSync(path.join(targetDir, 'src'), { recursive: true });
+    fs.mkdirSync(path.join(targetDir, 'public'), { recursive: true });
+    const sanitizedId = projectName.toLowerCase().replace(/[^a-z0-9_-]/g, '_');
+    // 1. app.json manifest
+    const appJson = {
+        appId: sanitizedId,
+        name: projectName.replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()),
+        version: '1.0.0',
+        description: `SuperApp Mini App: ${projectName}`,
+        entry: 'index.html',
+        category: 'utilities',
+        themeColor: '#0068FF',
+        permissions: [
+            'auth.userProfile',
+            'device.battery',
+            'device.network',
+            'storage',
+        ],
+    };
+    fs.writeFileSync(path.join(targetDir, 'app.json'), JSON.stringify(appJson, null, 2));
+    // 2. package.json
+    const packageJson = {
+        name: projectName,
+        private: true,
+        version: '1.0.0',
+        type: 'module',
+        scripts: {
+            dev: 'vite',
+            build: 'tsc && vite build',
+            preview: 'vite preview',
+        },
+        dependencies: {
+            '@vqh2602/mini-app-sdk': '^1.0.0',
+        },
+        devDependencies: {
+            typescript: '^5.6.3',
+            vite: '^5.4.11',
+        },
+    };
+    fs.writeFileSync(path.join(targetDir, 'package.json'), JSON.stringify(packageJson, null, 2));
+    // 3. tsconfig.json
+    const tsconfig = {
+        compilerOptions: {
+            target: 'ES2020',
+            useDefineForClassFields: true,
+            module: 'ESNext',
+            lib: ['ES2020', 'DOM', 'DOM.Iterable'],
+            skipLibCheck: true,
+            moduleResolution: 'bundler',
+            allowImportingTsExtensions: true,
+            resolveJsonModule: true,
+            isolatedModules: true,
+            noEmit: true,
+            strict: true,
+            noUnusedLocals: true,
+            noUnusedParameters: true,
+            noFallthroughCasesInSwitch: true,
+        },
+        include: ['src'],
+    };
+    fs.writeFileSync(path.join(targetDir, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2));
+    // 4. vite.config.ts
+    const viteConfig = `import { defineConfig } from 'vite';
+
+export default defineConfig({
+  base: './',
+  server: {
+    port: 3000,
+  },
+  build: {
+    outDir: 'dist',
+    assetsDir: 'assets',
+  },
+});
+`;
+    fs.writeFileSync(path.join(targetDir, 'vite.config.ts'), viteConfig);
+    // 5. index.html
+    const indexHtml = `<!DOCTYPE html>
+<html lang="vi">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
+    <title>${appJson.name}</title>
+    <style>
+      * { box-sizing: border-box; margin: 0; padding: 0; }
+      body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #f8fafc; color: #0f172a; padding: 16px; }
+      .card { background: white; border-radius: 12px; padding: 16px; margin-bottom: 16px; box-shadow: 0 1px 3px rgba(0,0,0,0.08); }
+      .btn { display: block; width: 100%; padding: 12px; border-radius: 8px; border: none; font-weight: 600; font-size: 14px; cursor: pointer; margin-bottom: 8px; }
+      .btn-primary { background: #0068FF; color: white; }
+      .btn-success { background: #10B981; color: white; }
+      .btn-secondary { background: #e2e8f0; color: #334155; }
+      h1 { font-size: 20px; font-weight: 700; margin-bottom: 4px; }
+      p { font-size: 13px; color: #64748b; line-height: 1.5; }
+      pre { background: #0f172a; color: #38bdf8; padding: 12px; border-radius: 8px; font-size: 12px; overflow-x: auto; max-height: 200px; }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h1>🚀 ${appJson.name}</h1>
+      <p>SuperApp Mini App SDK Demo Starter</p>
+    </div>
+
+    <div class="card">
+      <button id="btnLogin" class="btn btn-primary">👤 1. Đăng nhập SuperApp</button>
+      <button id="btnPay" class="btn btn-success">💳 2. Thanh toán đơn hàng</button>
+      <button id="btnDevice" class="btn btn-secondary">📱 3. Kiểm tra thông tin thiết bị</button>
+      <button id="btnToast" class="btn btn-secondary">🔔 4. Hiển thị thông báo Toast</button>
+    </div>
+
+    <div class="card">
+      <p style="font-weight: 600; margin-bottom: 8px;">Kết quả phản hồi:</p>
+      <pre id="output">Sẵn sàng gọi SDK...</pre>
+    </div>
+
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+`;
+    fs.writeFileSync(path.join(targetDir, 'index.html'), indexHtml);
+    // 6. src/main.ts
+    const mainTs = `import superApp from '@vqh2602/mini-app-sdk';
+
+const outputEl = document.getElementById('output') as HTMLPreElement;
+
+function log(data: any) {
+  outputEl.textContent = JSON.stringify(data, null, 2);
+}
+
+// 1. Đăng nhập
+document.getElementById('btnLogin')?.addEventListener('click', async () => {
+  try {
+    const res = await superApp.auth.login({ scopes: ['user.profile', 'user.phone'] });
+    log(res);
+    await superApp.ui.showToast(\`Xin chào \${res.user.name}!\`);
+  } catch (err: any) {
+    log({ error: err });
+  }
+});
+
+// 2. Thanh toán
+document.getElementById('btnPay')?.addEventListener('click', async () => {
+  try {
+    const res = await superApp.payment.requestPayment({
+      orderId: 'ORDER_' + Date.now(),
+      amount: 45000,
+      description: 'Thanh toán đơn hàng mẫu Mini App',
+    });
+    log(res);
+    await superApp.ui.showToast('Thanh toán thành công!');
+  } catch (err: any) {
+    log({ error: err });
+  }
+});
+
+// 3. Thông tin thiết bị
+document.getElementById('btnDevice')?.addEventListener('click', async () => {
+  try {
+    const battery = await superApp.device.getBatteryInfo();
+    const network = await superApp.device.getNetworkInfo();
+    const system = await superApp.device.getSystemInfo();
+    log({ battery, network, system });
+  } catch (err: any) {
+    log({ error: err });
+  }
+});
+
+// 4. Toast & Rung
+document.getElementById('btnToast')?.addEventListener('click', async () => {
+  await superApp.device.vibrate('light');
+  await superApp.ui.showToast('Thông báo Toast từ SuperApp SDK');
+});
+`;
+    fs.writeFileSync(path.join(targetDir, 'src/main.ts'), mainTs);
+    // 7. .gitignore
+    const gitignore = `node_modules
+dist
+.DS_Store
+*.local
+`;
+    fs.writeFileSync(path.join(targetDir, '.gitignore'), gitignore);
+    // 8. README.md
+    const readme = `# ${projectName}
+
+Dự án Mini App chạy trên nền tảng SuperApp.
+
+## Bắt đầu
+
+\`\`\`bash
+# 1. Cài đặt thư viện
+npm install
+
+# 2. Khởi chạy dev server & simulator
+npx miniapp dev
+
+# 3. Đóng gói sản phẩm
+npx miniapp build
+
+# 4. Xuất bản lên SuperApp Dynamic Registry
+npx miniapp upload
+\`\`\`
+`;
+    fs.writeFileSync(path.join(targetDir, 'README.md'), readme);
+    logger.step(2, 3, 'Khởi tạo mã nguồn và file cấu hình manifest app.json thành công!');
+    logger.step(3, 3, 'Hoàn tất.');
+    logger.success(`Mini App "${projectName}" đã sẵn sàng!`);
+    console.log(`\nTiếp theo, hãy thực hiện:\n  cd ${projectName}\n  npm install\n  npx miniapp dev\n`);
+}
+//# sourceMappingURL=create.js.map

package/dist/cli/commands/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../src/cli/commands/create.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/dev.d.ts

@@ -0,0 +1,8 @@
+export interface DevCommandOptions {
+    port?: string;
+    simulatorPort?: string;
+    open?: boolean;
+    noSimulator?: boolean;
+}
+export declare function devServer(options?: DevCommandOptions): Promise<void>;
+//# sourceMappingURL=dev.d.ts.map

package/dist/cli/commands/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/dev.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,wBAAsB,SAAS,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuC9E"}

package/dist/cli/commands/dev.js

@@ -0,0 +1,41 @@
+import { spawn } from 'node:child_process';
+import { loadManifest } from '../utils/config.js';
+import { logger } from '../utils/logger.js';
+import { startSimulatorServer } from '../utils/server.js';
+export async function devServer(options = {}) {
+    const manifest = loadManifest();
+    const port = options.port || '3000';
+    const simulatorPort = options.simulatorPort || '5175';
+    logger.title(`Khởi chạy Mini App Development Server`);
+    logger.info(`Đang chạy ứng dụng: ${manifest.name} (${manifest.appId})`);
+    let simServer = null;
+    if (!options.noSimulator) {
+        try {
+            simServer = startSimulatorServer(parseInt(simulatorPort, 10));
+        }
+        catch (e) {
+            logger.warn(`Không thể khởi chạy Simulator trên cổng ${simulatorPort}`);
+        }
+    }
+    logger.info(`Vite Server: http://localhost:${port}`);
+    logger.info(`Browser Simulator: http://localhost:${simulatorPort}/?url=http://localhost:${port}`);
+    const child = spawn('npx', ['vite', '--port', port], {
+        stdio: 'inherit',
+        shell: true,
+    });
+    child.on('error', (err) => {
+        logger.error('Lỗi khởi động Vite Dev Server:', err);
+    });
+    process.on('SIGINT', () => {
+        logger.info('Đang dừng Development Server & Simulator...');
+        if (simServer) {
+            try {
+                simServer.close();
+            }
+            catch (_) { }
+        }
+        child.kill('SIGINT');
+        process.exit(0);
+    });
+}
+//# sourceMappingURL=dev.js.map

package/dist/cli/commands/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.js","sourceRoot":"","sources":["../../../src/cli/commands/dev.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAS1D,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,UAA6B,EAAE;IAC7D,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;IAChC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC;IACpC,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,MAAM,CAAC;IAEtD,MAAM,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;IACtD,MAAM,CAAC,IAAI,CAAC,uBAAuB,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC;IAExE,IAAI,SAAS,GAAQ,IAAI,CAAC;IAC1B,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,SAAS,GAAG,oBAAoB,CAAC,QAAQ,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,CAAC;QAChE,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,CAAC,IAAI,CAAC,2CAA2C,aAAa,EAAE,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,iCAAiC,IAAI,EAAE,CAAC,CAAC;IACrD,MAAM,CAAC,IAAI,CAAC,uCAAuC,aAAa,0BAA0B,IAAI,EAAE,CAAC,CAAC;IAElG,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE;QACnD,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,IAAI;KACZ,CAAC,CAAC;IAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;QACxB,MAAM,CAAC,KAAK,CAAC,gCAAgC,EAAE,GAAG,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;QACxB,MAAM,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAC;QAC3D,IAAI,SAAS,EAAE,CAAC;YACd,IAAI,CAAC;gBACH,SAAS,CAAC,KAAK,EAAE,CAAC;YACpB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC,CAAA,CAAC;QAChB,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/cli/commands/doctor.d.ts

@@ -0,0 +1,2 @@
+export declare function runDoctor(): Promise<void>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/cli/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAIA,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAyC/C"}