From 83a4958d03cc38dd49dbc0f2323532b0bcdc4c1c Mon Sep 17 00:00:00 2001 From: Abner <22141172+Silentely@users.noreply.github.com> Date: Fri, 31 Oct 2025 20:44:40 +0800 Subject: [PATCH] =?UTF-8?q?docs(readme):=20=E6=B7=BB=E5=8A=A0=E8=8B=B1?= =?UTF-8?q?=E6=96=87=E7=89=88README=E5=B9=B6=E4=BC=98=E5=8C=96=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E9=93=BE=E6=8E=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 README_EN.md 英文档，支持国际化访问，并在中文 README 中添加英文版本跳转链接。 同时更新了文档中的用户指南和参考文档链接，补充对应的中英文对照，提升多语言使用体验。 --- README.md | 9 +- README_EN.md | 293 ++++++++++++++++++++++ docs/PERFORMANCE.md | 233 ----------------- docs/User_Guide_EN.md | 67 +++++ docs/reference/README_giffgaff_esim_EN.md | 205 +++++++++++++++ docs/reference/README_simyo_esim_EN.md | 263 +++++++++++++++++++ 6 files changed, 833 insertions(+), 237 deletions(-) create mode 100644 README_EN.md delete mode 100644 docs/PERFORMANCE.md create mode 100644 docs/User_Guide_EN.md create mode 100644 docs/reference/README_giffgaff_esim_EN.md create mode 100644 docs/reference/README_simyo_esim_EN.md diff --git a/README.md b/README.md index 6ef8c46..872afe0 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,8 @@ 专为Giffgaff和Simyo用户设计的现代化eSIM管理工具集，支持完整的eSIM申请、激活和二维码生成流程。 +[:us: English Version](README_EN.md) + ## ✨ 功能特性 ### 🇬🇧 Giffgaff eSIM工具 @@ -86,10 +88,9 @@ 5. **扫码安装** - 使用生成的二维码在新设备上安装 ### 📚 详细文档 -- **[Giffgaff使用教程](./docs/User_Guide.md)** - 图文及视频完整操作指南 -- [Giffgaff详细说明](./docs/reference/README_giffgaff_esim.md) -- [Simyo详细说明](./docs/reference/README_simyo_esim.md) -- [性能优化指南](./docs/PERFORMANCE.md) +- **[Giffgaff使用教程](./docs/User_Guide.md)** - 图文及视频完整操作指南 | [English](./docs/User_Guide_EN.md) +- [Giffgaff详细说明](./docs/reference/README_giffgaff_esim.md) | [English](./docs/reference/README_giffgaff_esim_EN.md) +- [Simyo详细说明](./docs/reference/README_simyo_esim.md) | [English](./docs/reference/README_simyo_esim_EN.md) ## 🚀 本地部署 diff --git a/README_EN.md b/README_EN.md new file mode 100644 index 0000000..efce56b --- /dev/null +++ b/README_EN.md @@ -0,0 +1,293 @@ +# eSIM Tools 🚀 + +Modern eSIM management toolkit designed for Giffgaff and Simyo users, supporting complete eSIM application, activation, and QR code generation processes. + +[:cn: 中文版本](README.md) + +## ✨ Features + +### 🇬🇧 Giffgaff eSIM Tools +- **OAuth 2.0 PKCE Authentication** - Secure authentication flow +- **Smart Cookie Login** - Fast login without OAuth +- **MFA Multi-Factor Authentication** - Email/SMS verification code support +- **SMS Verification Activation** - Fully automatic eSIM application and activation (✅ Recommended) +- **GraphQL API Integration** - Complete API call chain +- **LPA QR Code Generation** - Standard eSIM activation code +- ~~**Manual Activation Guide**~~ - Discontinued on October 8, 2025 + +### 🇳🇱 Simyo eSIM Tools +- **Account Login Verification** - Dutch phone number format validation +- **Device Replacement Support** - Complete SIM card replacement process +- **SMS Verification Code** - Automatic sending and verification processing +- **Instant QR Code Generation** - One-click generation of scannable activation codes +- **Installation Confirmation** - Ensures eSIM is correctly activated + +## 🖼️ Interface Preview + +> Below are functional screenshots of the main pages for quick understanding of the tool interface and core operation paths. + +### Home Page + +![Home - Feature Overview](./src/assets/images/home-preview.jpg) + +### Giffgaff eSIM Tools + +![Giffgaff - Tool Interface](./src/assets/images/giffgaff-preview.jpg) + +### Simyo eSIM Tools + +![Simyo - Tool Interface](./src/assets/images/simyo-preview.jpg) + +## 🌐 Online Usage + +### 🚀 Online Service (Recommended) +**Full Version**: [https://esim.cosr.eu.org](https://esim.cosr.eu.org) +- ✅ Supports all eSIM operations and processes +- ✅ Performance optimized, supports offline usage +- ✅ Regular updates and maintenance + +### 🎁 New User Offers +- **Simyo Users**: New sign-ups enjoy [extra €5 credit](https://vriendendeal.simyo.nl/prepaid/AZzwPzb) +- **Giffgaff Users**: New sign-ups enjoy [extra £5 credit](https://www.giffgaff.com/orders/affiliate/mowal44_1653194386268) + +## 📋 User Guide + +### 🇬🇧 Giffgaff eSIM Application Process (Recommended: SMS Verification Activation) +1. **Authentication** - OAuth login or Cookie fast login +2. **Email/SMS Verification** - Enter received MFA verification code +3. **Get Member Information** - Automatically retrieve account information +4. **SMS Verification Activation** - Select "SMS Verification Activation" (Recommended) + - Click "Send Verification Code" + - Enter the 6-digit SMS verification code received + - System automatically completes booking, exchange, and activation +5. **Get QR Code** - Automatically generates LPA activation code and QR code + +> ✅ **Recommended SMS Verification Activation**: Fully automated process, no manual operation required +> +> ⚠️ **Discontinued Feature**: Manual activation method was officially fixed and discontinued by Giffgaff on October 8, 2025 +> +> 📖 **Detailed Tutorial**: See [Giffgaff User Guide](./docs/reference/README_giffgaff_esim.md) for complete图文 and video operation guide + +### 🇳🇱 Simyo eSIM Application Process +1. **Account Login** - Enter Dutch phone number (starting with 06) and password +2. **Select Service** - New application or device replacement +3. **Verification Code Processing** - SMS or customer service verification code verification +4. **Get Configuration** - System generates eSIM configuration information +5. **Scan to Install** - Use the generated QR code to install on new device + +### 📚 Detailed Documentation +- **[Giffgaff User Guide](./docs/User_Guide.md)** - Complete图文 and video operation guide | [中文版](./docs/User_Guide_EN.md) +- [Giffgaff Detailed Instructions](./docs/reference/README_giffgaff_esim.md) | [中文版](./docs/reference/README_giffgaff_esim_EN.md) +- [Simyo Detailed Instructions](./docs/reference/README_simyo_esim.md) | [中文版](./docs/reference/README_simyo_esim_EN.md) +- [Performance Optimization Guide](./docs/PERFORMANCE.md) + +## 🚀 Local Deployment + +### Quick Start + +1. **Clone Repository** + ```bash + git clone https://github.com/Silentely/eSIM-Tools.git + cd eSIM-Tools + ``` + +2. **Install Dependencies** + ```bash + npm install + ``` + +3. **Start Proxy Server** + ```bash + # Windows + start_simyo_server.bat + + # macOS/Linux + ./start_simyo_server.sh + + # Or manually start + npm start + ``` + +4. **Access Application** + ``` + http://localhost:3000 + ``` + +### Requirements +- **Modern Browser**: Chrome 88+, Firefox 85+, Safari 14+, Edge 88+ +- **Development Environment**: Node.js >= 18.0.0, npm >= 8.0.0 (only needed for local development) + +## 🔧 Technical Architecture + +### Frontend Tech Stack +- **HTML5/CSS3** - Responsive design, modern UI +- **JavaScript ES6+** - Modular architecture, modern syntax features +- **Bootstrap 5** - Responsive UI framework +- **Service Worker** - Offline support and cache optimization + +### Backend Architecture +- **Production**: Netlify Functions - Serverless functions handling API proxy +- **Development**: Node.js Express - Local development server +- **CORS Handling** - Unified cross-origin request solution +- **Session Management** - Secure local storage and automatic expiration mechanism + +### 🚀 Performance Optimization +- **Resource Compression**: Webpack + TerserPlugin, compression rate 65%+ +- **Service Worker**: Offline caching and network status monitoring +- **Image Optimization**: WebP format support, automatic compression +- **Code Splitting**: Automatic separation of third-party libraries, reduced initial loading time + +> Detailed performance optimization documentation can be found in [PERFORMANCE.md](./docs/PERFORMANCE.md) + +### Service Time Information +- **Giffgaff Service Window**: UK Time 04:30 – 21:30 (Europe/London) +- **Operations Outside Window**: May fail or be unstable, UI displays local time compared to UK time + +## 📦 Deployment Methods + +### 🌟 Recommended: Online Service +Use hosted version [https://esim.cosr.eu.org](https://esim.cosr.eu.org) +- No deployment configuration needed, ready to use +- Automatic updates, stable and reliable +- Full feature support + +### 🔧 Self-hosted: Netlify +1. Fork this repository to your GitHub account +2. Connect GitHub repository in [Netlify](https://app.netlify.com) +3. Build settings: + - Build command: `echo 'No build needed'` + - Publish directory: `.` +4. Deployment complete, get your custom domain + +### ⚙️ Local Development +```bash +# Clone repository +git clone https://github.com/Silentely/eSIM-Tools.git +cd eSIM-Tools + +# Install dependencies and start +npm install +npm start + +# Access http://localhost:3000 +``` + +## ❓ Frequently Asked Questions + +### Giffgaff Related +**Q: Which activation method is recommended?** +A: Recommend using "SMS Verification Activation", fully automated process, just enter the SMS verification code to complete all steps. + +**Q: How long does SMS verification activation take?** +A: Usually 1-2 minutes. Send verification code → Enter verification code → Automatically complete booking, exchange and activation → Get QR code. + +**Q: Can manual activation still be used?** +A: Manual activation method was officially fixed and discontinued by Giffgaff on October 8, 2025. Please use SMS verification activation. + +**Q: What if I accidentally close the page?** +A: After re-login, the system will continue from the recoverable node. It is recommended to keep the page open until activation is complete. + +### Simyo Related +**Q: Which phone number formats are supported?** +A: Only Dutch phone numbers (10-digit numbers starting with 06). + +**Q: What if I don't receive the verification code?** +A: You can choose the customer service verification code option, or check SMS blocking settings. + +## ⚠️ Important Notes + +### Scope of Application +- **Giffgaff**: UK users only +- **Simyo**: Netherlands users only (06 prefix phone numbers) + +### Security and Privacy +- ✅ All data processing is done locally +- ✅ Does not store user credential information +- ✅ Recommended to use in secure network environment +- ✅ Open source and transparent, code auditable + +## 📁 Project Structure + +``` +eSIM-Tools/ +├── 📄 index.html # Main page +├── 🖥️ server.js # Local development server +├── 📦 package.json # Project configuration +├── 📂 src/ # Source code +│ ├── 🇬🇧 giffgaff/ # Giffgaff tools +│ ├── 🇳🇱 simyo/ # Simyo tools +│ ├── 🎨 styles/ # Style files +│ └── ⚙️ js/ # JavaScript modules +├── 🌐 netlify/ # Serverless functions +│ └── functions/ # API proxy +├── 📚 docs/ # Project documentation +│ ├── guides/ # User guides +│ ├── reference/ # Reference documents +│ └── fixes/ # Issue fixes +├── 🧪 tests/ # Test files +└── 🛠️ scripts/ # Deployment scripts +``` + +### Cross-Origin Solutions +1. **🌟 Recommended**: Use online service [esim.cosr.eu.org](https://esim.cosr.eu.org) +2. **🔧 Netlify Functions**: Automatic API proxy +3. **💻 Local Proxy**: Node.js development server +4. **📖 Detailed Explanation**: [CORS Solution Document](./docs/guides/CORS_SOLUTION.md) + +## 🧪 Testing + +Project includes comprehensive test suite: +- **Unit Tests** - Core functions and modules testing +- **Integration Tests** - API calls and process testing +- **End-to-End Tests** - Complete user flow verification + +```bash +# Run test suite +npm test + +# Test in browser +open tests/test_giffgaff_esim.html +open tests/test_simyo_esim.html +``` + +## 🤝 Contribution Guidelines + +Contributions and suggestions welcome! + +### How to Participate +1. 🍴 Fork project repository +2. 🌿 Create feature branch (`git checkout -b feature/AmazingFeature`) +3. 💾 Commit changes (`git commit -m 'Add AmazingFeature'`) +4. 📤 Push branch (`git push origin feature/AmazingFeature`) +5. 🔃 Create Pull Request + +### Development Standards +- Follow existing code style +- Add necessary test cases +- Update relevant documentation + +## 📞 Support and Feedback + +Having issues or suggestions? +- 📋 [Submit Issue](https://github.com/Silentely/eSIM-Tools/issues) +- 📖 View [Project Documentation](./docs/) +- 💬 Participate in community discussions + +## 📄 License + +- All code in this project, unless otherwise stated, is released under the [MIT License](LICENSE). +- README.MD, wiki and other resources of this project are based on [CC BY-NC-SA 4.0][CC-NC-SA-4.0] which means you can copy and redistribute the content of this project,
+ but you must also **provide author information and license statement**. At the same time you **cannot use this project for commercial purposes**, according to our narrow interpretation
+ (additional clause), any **profit-making activities are considered commercial use**. +- Please use this project in compliance with local laws and regulations. + +## ⚖️ Disclaimer + +This tool is for learning and personal use only. Please comply with relevant terms of service. The developer is not responsible for any problems arising from the use of this tool. Please use in compliance with local laws and regulations. + +[github-hosts]: https://raw.githubusercontent.com/racaljk/hosts/master/hosts "hosts on Github" +[CC-NC-SA-4.0]: https://creativecommons.org/licenses/by-nc-sa/4.0/ + +
+ Made with ❤️ by Silentely +
\ No newline at end of file diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.md deleted file mode 100644 index 513897b..0000000 --- a/docs/PERFORMANCE.md +++ /dev/null @@ -1,233 +0,0 @@ -# eSIM Tools 性能优化指南 - -## 概述 - -本项目已实施全面的性能优化，包括资源压缩、Service Worker离线支持、图片优化、微交互动画等。 - -## 优化特性 - -### 1. 资源压缩与优化 - -#### Webpack构建优化 -- **代码分割**: 自动分离第三方库和业务代码 -- **Tree Shaking**: 移除未使用的代码 -- **压缩**: 使用TerserPlugin压缩JavaScript -- **CSS优化**: 使用PostCSS和cssnano压缩CSS - -#### 文件压缩 -- **Gzip压缩**: 自动生成.gz文件 -- **Brotli压缩**: 生成.br文件（如果支持） -- **压缩率**: 通常可达到60-80%的压缩率 - -### 2. Service Worker离线支持 - -#### 缓存策略 -- **静态资源**: Cache First策略 -- **API请求**: Network First策略 -- **二维码API**: Cache First策略（24小时缓存） - -#### 离线功能 -- 应用可在离线状态下使用 -- 自动更新检测和通知 -- 网络状态实时显示 - -### 3. 图片优化 - -#### WebP支持 -- 自动检测浏览器WebP支持 -- 优先使用WebP格式 -- 降级到JPEG/PNG - -#### 图片压缩 -- 自动压缩图片文件 -- 生成多种格式（WebP、JPEG、PNG） -- 保持视觉质量的同时减少文件大小 - -### 4. 微交互动画 - -#### 按钮反馈 -- 点击时的缩放效果 -- 触摸设备的优化反馈 -- 涟漪效果动画 - -#### 加载状态 -- 优雅的加载指示器 -- 进度条动画 -- 状态切换动画 - -### 5. 移动端优化 - -#### 触摸优化 -- 防止双击缩放 -- 触摸反馈优化 -- 滚动性能优化 - -#### 响应式设计 -- 移动端专用动画 -- 触摸友好的交互 -- 性能优先的动画 - -## 使用方法 - -### 开发环境 - -```bash -# 安装依赖 -npm install - -# 启动开发服务器 -npm run dev - -# 构建优化版本 -npm run build - -# 压缩构建文件 -npm run compress -``` - -### 生产部署 - -```bash -# 完整构建流程 -npm run build - -# 部署到Netlify -npm run deploy -``` - -## 性能监控 - -### 内置监控 -- 页面加载性能分析 -- 网络请求监控 -- 缓存命中率统计 - -### 性能指标 -- **First Contentful Paint (FCP)**: < 1.5s -- **Largest Contentful Paint (LCP)**: < 2.5s -- **Cumulative Layout Shift (CLS)**: < 0.1 -- **First Input Delay (FID)**: < 100ms - -## 优化配置 - -### Webpack配置 -```javascript -// webpack.config.js -module.exports = { - optimization: { - minimize: true, - splitChunks: { - chunks: 'all', - cacheGroups: { - vendor: { - test: /[\\/]node_modules[\\/]/, - name: 'vendors', - chunks: 'all' - } - } - } - } -} -``` - -### Service Worker配置 -```javascript -// sw.js -const STATIC_CACHE = 'static-v2.1.0'; -const DYNAMIC_CACHE = 'dynamic-v2.1.0'; - -// 缓存策略 -runtimeCaching: [ - { - urlPattern: /^https:\/\/api\.qrserver\.com/, - handler: 'CacheFirst', - options: { - cacheName: 'qr-cache', - expiration: { - maxEntries: 50, - maxAgeSeconds: 24 * 60 * 60 - } - } - } -] -``` - -## 最佳实践 - -### 1. 图片优化 -- 使用WebP格式 -- 设置合适的压缩质量 -- 实现懒加载 - -### 2. 代码优化 -- 避免不必要的DOM操作 -- 使用防抖和节流 -- 优化事件监听器 - -### 3. 缓存策略 -- 合理设置缓存时间 -- 实现缓存更新机制 -- 监控缓存命中率 - -### 4. 用户体验 -- 提供加载状态反馈 -- 实现优雅的错误处理 -- 优化动画性能 - -## 故障排除 - -### 常见问题 - -1. **Service Worker不工作** - - 检查HTTPS环境 - - 清除浏览器缓存 - - 检查控制台错误 - -2. **图片加载失败** - - 检查WebP支持 - - 验证图片路径 - - 检查网络连接 - -3. **动画卡顿** - - 使用transform代替position - - 启用硬件加速 - - 优化动画帧率 - -### 调试工具 - -```javascript -// 性能监控 -performanceOptimizer.setupPerformanceMonitoring(); - -// 网络状态检查 -console.log('在线状态:', navigator.onLine); - -// 缓存状态 -caches.keys().then(keys => console.log('缓存列表:', keys)); -``` - -## 更新日志 - -### v2.1.0 -- 添加Service Worker离线支持 -- 实现图片WebP优化 -- 添加微交互动画 -- 优化移动端体验 -- 实现资源压缩 - -### v2.0.0 -- 基础性能优化 -- 代码分割 -- CSS压缩 -- 基础缓存策略 - -## 贡献指南 - -1. 遵循性能优先原则 -2. 测试所有优化功能 -3. 监控性能指标 -4. 更新相关文档 - -## 许可证 - -MIT License - 详见LICENSE文件 \ No newline at end of file diff --git a/docs/User_Guide_EN.md b/docs/User_Guide_EN.md new file mode 100644 index 0000000..cc1cc40 --- /dev/null +++ b/docs/User_Guide_EN.md @@ -0,0 +1,67 @@ +# Giffgaff User Guide + +> 🎬 Video Tutorial - Giffgaff eSIM Replacement Operation Demo + +Your browser does not support video playback. Please [click here](https://github.com/user-attachments/assets/306dacb4-0a06-4930-bf35-3711d0f63720) to download the video. + +[giffgaff.webm](https://github.com/user-attachments/assets/d4fbd0ff-b8bc-4477-a0c4-45698fe4802c) + +## 1. Open Giffgaff eSIM Replacement Web Page + +Visit the eSIM Tools website and select the Giffgaff eSIM tool. + +## 2. Select Login Method + +Choose OAuth or Cookies login method (OAuth method is recommended) + +![Select Login Method](image/101.jpg) + +### OAuth Login + +OAuth method requires obtaining the callback URL. For instructions on how to get it, please refer to the page instructions: + +![Get Callback URL Instructions](image/102.jpg) + +1. Click the "Login with OAuth" button +2. In the newly opened page, enter your Giffgaff username and password and click login (please open the browser developer tools network panel in advance) +3. Enter the email verification code +4. Find the callback URL in the network panel of the developer tools (format: `giffgaff://auth/callback/?code=ABC123&state=XYZ789`) + +![Get Callback URL](image/103.jpg) + +5. Enter the obtained callback URL into the corresponding input box on the eSIM replacement page and click "Process Callback" + +![Enter Callback URL](image/104.jpg) + +## 3. MFA Authentication + +After processing the callback, you will be automatically redirected to the second step, select email/SMS verification code method to obtain MFA authentication: + +![MFA Authentication](image/105.jpg) + +Enter the obtained verification code and click "Verify": + +![Enter Verification Code](image/106.jpg) + +## 4. Get Member Information + +After successful verification, you will be automatically redirected to the third step, the get Giffgaff member information page: + +![Get Member Information](image/107.jpg) + +Click "Get Member Information" to go to the fourth step of applying/activating eSIM: + +![Apply/Activate eSIM](image/114.jpg) + +## 5. Select and Activate eSIM + +Select SMS verification code activation and enter the SMS verification code, the system will automatically complete the eSIM replacement and generate QR code and LPA information: + +![Verification Code Page](image/115.jpg) + +After successful exchange, you will be redirected to the fifth step showing QR code and LPA information: + +![eSIM Information](image/116.jpg) +![eSIM Information 1](image/117.jpg) + +## 6. Use Native eSIM Phone to Complete Scanning \ No newline at end of file diff --git a/docs/reference/README_giffgaff_esim_EN.md b/docs/reference/README_giffgaff_esim_EN.md new file mode 100644 index 0000000..1e56bef --- /dev/null +++ b/docs/reference/README_giffgaff_esim_EN.md @@ -0,0 +1,205 @@ +# Giffgaff eSIM Application Tool +> QR code provider: Prefer `https://qrcode.show/`, and keep `quickchart.io` and `chart.googleapis.com` as alternatives. +A complete eSIM application web tool built based on the Giffgaff-swap-esim.json Postman script. + +## 🚀 Project Overview + +This is a complete web application that allows users to apply for and obtain Giffgaff eSIM directly through a browser, without using mobile apps or complex API tools. + +### Core Features +- ✅ OAuth 2.0 PKCE Authentication Process +- ✅ Email Verification Code (MFA) Verification +- ✅ GraphQL API Full Integration +- ✅ eSIM Reservation and Manual Activation Guidance +- ✅ eSIM Download Code Generation and QR Code Display +- ✅ Responsive Design, Mobile Device Support +- ✅ Complete Error Handling and User Experience Optimization + +## 📁 File Description + +### Main Files +- **`giffgaff_complete_esim.html`** - Complete eSIM Application Tool (Production Version) +- **`test_giffgaff_esim.html`** - Comprehensive Test Page (Development/Test Version) +- **`Giffgaff-swap-esim.json`** - Original Postman Script (Reference Document) +- **`giffgaff.html`**** - Original Simplified Version (Reference) + +### Reference Files +- **`simyo.html`** - Simyo eSIM Tool (Other Operator Reference) +- **`Simyo ESIM V2.postman_collection.json`** - Simyo API Script + +## 🔧 Technical Architecture + +### Frontend Technology Stack +- **HTML5** - Semantic Structure +- **CSS3** - Responsive Design, Bootstrap 5.3.0 +- **JavaScript (ES6+)** - Modern JavaScript Features +- **Font Awesome 6.0.0** - Icon Library + +### API Integration +- **OAuth 2.0 PKCE** - Secure Authentication Process +- **Giffgaff ID API** - User Authentication and MFA +- **Giffgaff GraphQL API** - Business Logic Processing +- **QR Code API** - QR Code Generation Service + +### Key API Endpoints +```javascript +const apiEndpoints = { + mfaChallenge: "https://id.giffgaff.com/v4/mfa/challenge/me", + mfaValidation: "https://id.giffgaff.com/v4/mfa/validation", + graphql: "https://publicapi.giffgaff.com/gateway/graphql", + qrcode: "https://qrcode.show/" +}; +``` + +## 🚦 Usage Process + +### Step 1: OAuth Login +1. Click "Start OAuth Login" +2. Complete Giffgaff account login on the pop-up page +3. Copy the callback URL and paste it into the input box +4. Click "Process Callback" to get the access token + +### Step 2: Email Verification +1. Click "Send Email Verification Code" +2. Check your email for the 6-digit verification code +3. Enter the verification code and click "Verify Email Verification Code" + +### Step 3: Get Member Information +1. Click "Get Member Information" +2. The system will display your Giffgaff account details + +### Step 4: Apply for eSIM +1. Click "Reserve eSIM" to get a new eSIM (status: RESERVED) +2. **Important: Keep the page open, do not close or refresh** +3. Copy the displayed activation code +4. Go to [Giffgaff Activation Page](https://www.giffgaff.com/activate) to manually activate the eSIM +5. On the activation page, enter the activation code and click "Activate your SIM" +6. Verify the information is correct and click "Yes, I want to replace my SIM" +7. After successful activation, return to this tool and click "I have completed manual activation, continue to next step" + +### Step 5: Get QR Code +1. Click "Get eSIM Token" +2. The system will generate the LPA string and QR code +3. Save the QR code image or copy the LPA string to an eSIM-enabled device + +## ⚠️ Important Notes + +### Security Warning +- **Physical SIM Card Will Be Invalid** - After performing SIM swap, the original physical SIM card will no longer work +- **Save Information Immediately** - eSIM information cannot be retrieved again after the page is closed +- **Personal Use Only** - Do not share your OAuth token or eSIM information + +### System Requirements +- **Modern Browser** - Chrome 80+, Firefox 75+, Safari 13+, Edge 80+ +- **HTTPS Environment** - Due to security restrictions, some features require HTTPS +- **JavaScript Enabled** - JavaScript must be enabled to work properly + +### Compatibility +- ✅ Desktop (Windows, macOS, Linux) +- ✅ Mobile (iOS, Android) +- ✅ Tablet Devices +- ⚠️ Some older browsers may not be supported + +## 🧪 Testing + +Use `test_giffgaff_esim.html` for functional testing: + +### Test Categories +1. **Unit Tests** - OAuth functions, URL parsing, state management, UI components +2. **Integration Tests** - OAuth process, MFA verification, GraphQL API, eSIM processing +3. **End-to-End Tests** - Complete process, error handling, responsive design +4. **Performance Tests** - API response time, memory usage monitoring + +### Running Tests +1. Open `test_giffgaff_esim.html` +2. Configure mock data (optional) +3. Click "Run All Tests" or select specific test categories +4. View test results and detailed logs + +## 📝 Development Instructions + +### Core Component Architecture +```javascript +// Global State Management +const appState = { + accessToken: "", // OAuth access token + codeVerifier: "", // PKCE code verifier + emailCodeRef: "", // Email verification reference + emailSignature: "", // MFA signature + memberId: "", // Member ID + esimSSN: "", // eSIM serial number + lpaString: "", // LPA download string + currentStep: 1 // Current step +}; +``` + +### Main Function Description +- `generateCodeVerifier()` - Generate PKCE code verifier +- `generateCodeChallenge()` - Generate PKCE code challenge +- `showSection(stepNumber)` - Show specified step +- `showStatus(element, message, type)` - Show status information +- `generateQRCode(data)` - Generate QR code + +### GraphQL Query Example +```graphql +# Get Member Information +query getMemberProfileAndSim { + memberProfile { + id + memberName + __typename + } + sim { + phoneNumber + status + __typename + } +} + +# Reserve eSIM +mutation reserveESim($input: ESimReservationInput!) { + reserveESim: reserveESim(input: $input) { + id + esim { + ssn + activationCode + __typename + } + __typename + } +} +``` + +## 🤝 Contribution Guidelines + +### Development Environment Setup +1. Clone or download project files +2. Run using local HTTP server (HTTPS recommended) +3. Configure test data and API endpoints + +### Code Standards +- Use modern JavaScript syntax (ES6+) +- Follow semantic HTML structure +- Maintain CSS modularity and responsive design +- Add detailed error handling and user feedback + +### Testing Requirements +- New features must include corresponding test cases +- Ensure all existing tests pass +- Performance tests to ensure reasonable response times + +## 📄 License + +This project is developed based on the original Postman script for learning and personal use only. Please comply with Giffgaff's terms of service and API usage policy. + +## 🙋‍♂️ Support + +If you have questions or suggestions, please: +1. First use the test page to verify functionality +2. Check browser console error messages +3. Confirm network connection and API availability +4. Refer to Giffgaff official documentation + +--- + +**Disclaimer**: This tool is developed solely for user convenience. Please ensure you understand the risks and consequences of eSIM conversion before use. The developer is not responsible for any losses caused by using this tool. \ No newline at end of file diff --git a/docs/reference/README_simyo_esim_EN.md b/docs/reference/README_simyo_esim_EN.md new file mode 100644 index 0000000..f08b5fe --- /dev/null +++ b/docs/reference/README_simyo_esim_EN.md @@ -0,0 +1,263 @@ +# Simyo NL eSIM Application Tool + +A complete eSIM application web tool built based on the Simyo ESIM V2.postman_collection.json Postman script. + +## 🚀 Project Overview + +This is a web application designed specifically for Simyo NL (Netherlands) users that allows users to apply for and manage Simyo eSIM directly through a browser, without using mobile apps or complex API tools. + +### Core Features +- ✅ Simyo Account Authentication Login +- ✅ eSIM Configuration Information Retrieval +- ✅ eSIM QR Code Generation and Display +- ✅ Device Replacement Support +- ✅ Installation Confirmation Function +- ✅ Responsive Design, Mobile Device Support +- ✅ Complete Error Handling and User Experience Optimization + +## 📁 File Description + +### Main Files +- **`simyo_complete_esim.html`** - Complete Simyo eSIM Application Tool (Production Version) +- **`test_simyo_esim.html`** - Comprehensive Test Page (Development/Test Version) +- **`Simyo ESIM V2.postman_collection.json`** - Original Postman Script (Reference Document) +- **`simyo.html`** - Original Simplified Version (Reference) + +## 🔧 Technical Architecture + +### Frontend Technology Stack +- **HTML5** - Semantic Structure +- **CSS3** - Responsive Design, Bootstrap 5.3.0, Simyo Brand Colors +- **JavaScript (ES6+)** - Modern JavaScript Features +- **Font Awesome 6.0.0** - Icon Library + +### API Integration +- **Simyo Sessions API** - User Authentication and Session Management +- **Simyo eSIM API** - eSIM Configuration Retrieval and Management +- **QR Code API** - QR Code Generation Service + +### Key API Endpoints +```javascript +const apiEndpoints = { + login: "https://appapi.simyo.nl/simyoapi/api/v1/sessions", + getEsim: "https://appapi.simyo.nl/simyoapi/api/v1/esim/get-by-customer", + confirmInstall: "https://appapi.simyo.nl/simyoapi/api/v1/esim/reorder-profile-installed", + qrcode: "https://qrcode.show/" +}; +``` + +## 🚦 Usage Process + +### Initial Registration and eSIM Installation + +#### Step 1: Account Login +1. Enter your Simyo phone number (06 prefix, 10 digits) +2. Enter your Simyo account password +3. Click "Login Account" for authentication + +#### Step 2: Get eSIM Information +1. Click "Get eSIM" +2. The system will retrieve your eSIM configuration information from the Simyo server +3. Display detailed information such as activation code, status, and associated number + +#### Step 3: Generate eSIM QR Code +1. Click "Generate QR Code" +2. The system will create an LPA format activation code +3. Generate a QR code for device scanning installation +4. You can copy the LPA string or download the QR code image + +#### Step 4: Confirm Installation (Optional) +1. Only needed when the app cannot log in or when changing devices +2. Click "Confirm Installation" to verify eSIM status + +### Device Replacement Process + +This tool now supports the complete device replacement process, including verification code processing: + +#### Method 1: Complete Device Replacement Using This Tool (Recommended) + +1. **Login Account** + - Login with your Simyo phone number and password + +2. **Select Device Replacement** + - After successful login, select the "Replace Device" option + +3. **Complete Device Replacement Process** + - **Step 2.1: Apply for New eSIM** - Notify the Simyo system that you want to replace your device + - **Step 2.2: Send Verification Code (Optional)** - Execute this step if you can receive SMS + - **Step 2.3: Confirm Verification Code** - Enter the 6-digit verification code received + +4. **Get eSIM Configuration** + - After successful verification, automatically proceed to the eSIM retrieval step + - Generate a new QR code for the new device + +5. **Install eSIM on New Device** + - Scan the generated QR code on the new device + - Or manually enter the LPA activation code + +6. **Confirm Installation** + - Use the "Confirm Installation" function to verify eSIM status + - Signal will be restored quickly after successful confirmation + +#### Method 2: Combined with APP Usage (Traditional Method) + +1. **Apply for Device Replacement/eSIM in Simyo APP** + - Open the official Simyo APP + - Select "Replace Device" or "Apply for eSIM" + - Fill in the received verification code + - **Stay on the next interface, do not continue operating** + +2. **Use This Tool to Generate QR Code** + - Re-login to your Simyo account + - Select "Get eSIM Directly" + - Generate a new QR code + +3. **Install eSIM on New Device** + - Scan the generated QR code on the new device + - Or manually enter the LPA activation code + - Enable the installed Simyo configuration + +4. **Confirm Installation (Recommended)** + - Use the "Confirm Installation" function of this tool + - Signal will be restored quickly after successful confirmation + +#### Verification Code Acquisition Instructions + +- **If you can receive SMS**: Execute step 2.1 and then immediately execute step 2.2, the verification code will be sent to your phone +- **If you cannot receive SMS**: Only execute step 2.1, then contact Simyo customer service for "verification code when replacing eSIM device" + - Customer service may require: number, name, birthday, address, postal code + - Please prepare this information in advance, which can be found in the Simyo APP + +## 💰 Number Preservation Service + +Simyo offers low-cost number preservation service with details: + +- **Payee**: ING BANK N.V. +- **IBAN**: `NL19INGB0007811670` +- **Amount**: 0.01 Euro +- **Remarks**: Your Simyo number (complete number starting with 06) + +## ⚠️ Important Notes + +### Usage Precautions +- **Netherlands Numbers Only** - Only for Simyo NL (Netherlands) users +- **Phone Number Format** - Must be 10-digit number starting with 06 +- **eSIM Device Requirements** - Ensure your device supports eSIM functionality +- **Network Connection** - Stable network connection required for API calls + +### Device Replacement Special Notes +- Please follow the process strictly when replacing devices +- Do not continue operating in the APP after applying, immediately use this tool +- Non-native eSIM devices need to send `install` and `enabled` notifications + +### System Requirements +- **Modern Browser** - Chrome 80+, Firefox 75+, Safari 13+, Edge 80+ +- **HTTPS Environment** - Due to security restrictions, some features require HTTPS +- **JavaScript Enabled** - JavaScript must be enabled to work properly + +## 🧪 Testing + +Use `test_simyo_esim.html` for functional testing: + +### Test Categories +1. **Unit Tests** - Phone number validation, API header generation, LPA format, UI components +2. **Integration Tests** - Login process, eSIM retrieval, QR code generation, installation confirmation +3. **End-to-End Tests** - Complete process, error handling, device replacement scenarios +4. **Performance Tests** - API response time, memory usage monitoring + +### Running Tests +1. Open `test_simyo_esim.html` +2. Configure mock data (optional) +3. Click "Run All Tests" or select specific test categories +4. View test results and detailed logs + +## 📝 Development Instructions + +### Core Component Architecture +```javascript +// Global State Management +const appState = { + sessionToken: "", // Simyo session token + activationCode: "", // eSIM activation code + phoneNumber: "", // User phone number + password: "", // User password + currentStep: 1 // Current step +}; +``` + +### Main Function Description +- `mockValidatePhoneNumber()` - Validate Dutch phone number format +- `createHeaders()` - Generate Simyo API request headers +- `showSection(stepNumber)` - Show specified step +- `showStatus(element, message, type)` - Show status information +- `generateQRCode(data)` - Generate eSIM QR code + +### API Call Example +```javascript +// Login Simyo Account +const response = await fetch('https://appapi.simyo.nl/simyoapi/api/v1/sessions', { + method: 'POST', + headers: createHeaders(false), + body: JSON.stringify({ + phoneNumber: '0613123712', + password: 'your_password' + }) +}); + +// Get eSIM Information +const esimResponse = await fetch('https://appapi.simyo.nl/simyoapi/api/v1/esim/get-by-customer', { + method: 'GET', + headers: createHeaders(true) // Include session token +}); +``` + +## 🔄 Differences from Giffgaff Tool + +| Feature | Simyo eSIM | Giffgaff eSIM | +|------|------------|---------------| +| **Authentication Method** | Username/password login | OAuth 2.0 PKCE | +| **MFA Verification** | No additional verification | Email verification code | +| **API Complexity** | Relatively simple | GraphQL + REST | +| **Number of Steps** | 4-step process | 5-step process | +| **Device Replacement** | Dedicated process support | Through SIM swap | +| **Number Preservation** | 0.01 Euro | According to normal plan | + +## 🤝 Contribution Guidelines + +### Development Environment Setup +1. Clone or download project files +2. Run using local HTTP server (HTTPS recommended) +3. Configure test data and API endpoints + +### Code Standards +- Use modern JavaScript syntax (ES6+) +- Follow semantic HTML structure +- Maintain CSS modularity and responsive design +- Add detailed error handling and user feedback + +### Testing Requirements +- New features must include corresponding test cases +- Ensure all existing tests pass +- Performance tests to ensure reasonable response times + +## 🔗 Related Resources + +- [Simyo Official Website](https://www.simyo.nl/) +- [eSIM Technical Description](https://en.wikipedia.org/wiki/ESIM) +- [Dutch Mobile Number Format](https://en.wikipedia.org/wiki/Telephone_numbers_in_the_Netherlands) + +## 📄 License + +This project is developed based on the original Simyo Postman script for learning and personal use only. Please comply with Simyo's terms of service and API usage policy. + +## 🙋‍♂️ Support + +If you have questions or suggestions, please: +1. First use the test page to verify functionality +2. Check browser console error messages +3. Confirm network connection and API availability +4. Refer to Simyo official documentation + +--- + +**Disclaimer**: This tool is developed solely for user convenience. Please ensure you understand the risks and consequences of eSIM conversion before use. The developer is not responsible for any losses caused by using this tool. Please ensure you have the right to use the related Simyo account and services. \ No newline at end of file