Bundles

Bundles 是 Capgo 的核心更新包。每个 bundle 包含构成应用内容的 web 资源（HTML、CSS、JS）。Bundles API 允许您管理这些更新包，包括列表显示和删除。

了解 Bundles

bundle 代表应用 web 内容的特定版本，包括：

• Version：bundle 的语义版本号
• Checksum：用于验证 bundle 完整性的唯一哈希
• Storage Info：有关 bundle 存储位置和方式的详细信息
• Native Requirements：原生应用的最低版本要求
• Metadata：创建时间、所有权和其他跟踪信息

手动 Bundle 创建（无需 CLI）

如何在不使用 Capgo CLI 的情况下手动创建和上传 bundle：

步骤 1：构建应用

首先，构建应用的 web 资源：

npm run build

步骤 2：使用与 Capgo CLI 相同的包创建 Bundle Zip

重要：使用与 Capgo CLI 内部使用完全相同的 JavaScript 包以确保兼容性。

安装所需的包

npm install adm-zip @tomasklaen/checksum

使用 JavaScript 创建 Zip Bundle（与 Capgo CLI 相同）

const fs = require('node:fs');
const path = require('node:path');
const os = require('node:os');
const AdmZip = require('adm-zip');
const { checksum: getChecksum } = require('@tomasklaen/checksum');

// Exact same implementation as Capgo CLI
function zipFileUnix(filePath) {
  const zip = new AdmZip();
  zip.addLocalFolder(filePath);
  return zip.toBuffer();
}

async function zipFileWindows(filePath) {
  console.log('Zipping file windows mode');
  const zip = new AdmZip();

  const addToZip = (folderPath, zipPath) => {
    const items = fs.readdirSync(folderPath);

    for (const item of items) {
      const itemPath = path.join(folderPath, item);
      const stats = fs.statSync(itemPath);

      if (stats.isFile()) {
        const fileContent = fs.readFileSync(itemPath);
        zip.addFile(path.join(zipPath, item).split(path.sep).join('/'), fileContent);
      } else if (stats.isDirectory()) {
        addToZip(itemPath, path.join(zipPath, item));
      }
    }
  };

  addToZip(filePath, '');
  return zip.toBuffer();
}

// Main zipFile function (exact same logic as CLI)
async function zipFile(filePath) {
  if (os.platform() === 'win32') {
    return zipFileWindows(filePath);
  } else {
    return zipFileUnix(filePath);
  }
}

async function createBundle(inputPath, outputPath, version) {
  // Create zip using exact same method as Capgo CLI
  const zipped = await zipFile(inputPath);

  // Write to file
  fs.writeFileSync(outputPath, zipped);

  // Calculate checksum using exact same package as CLI
  const checksum = await getChecksum(zipped, 'sha256');

  return {
    filename: path.basename(outputPath),
    version: version,
    size: zipped.length,
    checksum: checksum
  };
}

// Usage
async function main() {
  try {
    const result = await createBundle('./dist', './my-app-1.2.3.zip', '1.2.3');
    console.log('Bundle info:', JSON.stringify(result, null, 2));
  } catch (error) {
    console.error('Error creating bundle:', error);
  }
}

main();

步骤 3：使用与 CLI 相同的包计算 SHA256 校验和

const fs = require('node:fs');
const { checksum: getChecksum } = require('@tomasklaen/checksum');

async function calculateChecksum(filePath) {
  const fileBuffer = fs.readFileSync(filePath);
  // Use exact same package and method as Capgo CLI
  const checksum = await getChecksum(fileBuffer, 'sha256');
  return checksum;
}

// Usage
async function main() {
  const checksum = await calculateChecksum('./my-app-1.2.3.zip');
  console.log('Checksum:', checksum);
}

main();

步骤 4：将 Bundle 上传到存储

Upload your zip file to any web-accessible storage:

# Example: Upload to your server via scp
scp my-app-1.2.3.zip user@your-server.com:/var/www/bundles/

# Example: Upload to S3 using AWS CLI
aws s3 cp my-app-1.2.3.zip s3://your-bucket/bundles/

# Example: Upload via curl to a custom endpoint
curl -X POST https://your-storage-api.com/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@my-app-1.2.3.zip"

Important: Your bundle must be publicly accessible via HTTPS URL (no authentication required). Capgo’s servers need to download the bundle from this URL.

Examples of valid public URLs:

• https://your-storage.com/bundles/my-app-1.2.3.zip
• https://github.com/username/repo/releases/download/v1.2.3/bundle.zip
• https://cdn.jsdelivr.net/gh/username/repo@v1.2.3/dist.zip

步骤 5：向 Capgo API 注册 Bundle

Register the external bundle with Capgo using direct API calls:

async function registerWithCapgo(appId, version, bundleUrl, checksum, apiKey) {
  const fetch = require('node-fetch');

  // Create bundle version
  const response = await fetch('https://api.capgo.app/bundle/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'authorization': apiKey
    },
    body: JSON.stringify({
      app_id: appId,
      version: version,
      external_url: bundleUrl,
      checksum: checksum
    })
  });

  if (!response.ok) {
    throw new Error(`Failed to create bundle: ${response.statusText}`);
  }

  const data = await response.json();
  console.log('Bundle created:', data);

  return data;
}

API 参数

Parameter	Description	Required
app_id	Your app identifier	Yes
version	Semantic version (e.g., “1.2.3”)	Yes
external_url	Publicly accessible HTTPS URL where bundle can be downloaded (no auth required)	Yes
checksum	SHA256 checksum of the zip file	Yes

Bundle 结构要求

Your bundle zip must follow these requirements:

1. Root Index File: Must have index.html at the root level
2. Capacitor Integration: Must call notifyAppReady() in your app code
3. Asset Paths: Use relative paths for all assets

有效的 Bundle 结构

bundle.zip
├── index.html
├── assets/
│   ├── app.js
│   └── styles.css
└── images/

完整的手动工作流程示例

Simple Node.js script to zip, checksum, and upload to Capgo:

const fs = require('node:fs');
const os = require('node:os');
const AdmZip = require('adm-zip');
const { checksum: getChecksum } = require('@tomasklaen/checksum');
const fetch = require('node-fetch');

async function deployToCapgo() {
  const APP_ID = 'com.example.app';
  const VERSION = '1.2.3';
  const BUNDLE_URL = 'https://your-storage.com/bundles/app-1.2.3.zip';
  const API_KEY = process.env.CAPGO_API_KEY;

  // 1. Create zip (same as Capgo CLI)
  const zip = new AdmZip();
  zip.addLocalFolder('./dist');
  const zipped = zip.toBuffer();

  // 2. Calculate checksum (same as Capgo CLI)
  const checksum = await getChecksum(zipped, 'sha256');
  console.log('Checksum:', checksum);

  // 3. Upload to your storage (replace with your upload logic)
  // fs.writeFileSync('./bundle.zip', zipped);
  // ... upload bundle.zip to your storage ...

  // 4. Register with Capgo API
  const response = await fetch('https://api.capgo.app/bundle/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'authorization': API_KEY
    },
    body: JSON.stringify({
      app_id: APP_ID,
      version: VERSION,
      external_url: BUNDLE_URL,
      checksum: checksum
    })
  });

  if (!response.ok) {
    throw new Error(`Failed: ${response.statusText}`);
  }

  console.log('Bundle registered with Capgo!');
}

deployToCapgo().catch(console.error);

Install dependencies:

npm install adm-zip @tomasklaen/checksum node-fetch

校验和验证

JavaScript 校验和计算（与 Capgo CLI 相同）

Use the exact same package and method that Capgo CLI uses internally:

const fs = require('node:fs');
const { checksum: getChecksum } = require('@tomasklaen/checksum');

async function calculateChecksum(filePath) {
  const fileBuffer = fs.readFileSync(filePath);
  // Use exact same package and method as Capgo CLI
  const checksum = await getChecksum(fileBuffer, 'sha256');
  return checksum;
}

// Verify checksum matches
async function verifyChecksum(filePath, expectedChecksum) {
  const actualChecksum = await calculateChecksum(filePath);
  const isValid = actualChecksum === expectedChecksum;

  console.log(`File: ${filePath}`);
  console.log(`Expected: ${expectedChecksum}`);
  console.log(`Actual:   ${actualChecksum}`);
  console.log(`Valid:    ${isValid}`);

  return isValid;
}

// Usage
async function main() {
  const bundleChecksum = await calculateChecksum('./my-app-1.2.3.zip');
  console.log('SHA256 Checksum:', bundleChecksum);
}

main();

校验和的重要性

• Bundle Integrity: Ensures the bundle hasn’t been corrupted during transfer
• API Verification: Capgo verifies checksums before accepting bundles
• Plugin Verification: The mobile plugin verifies checksums before applying updates

Best Practices

1. Version Management: Use semantic versioning consistently
2. Storage Optimization: Remove unused bundles periodically
3. Version Compatibility: Set appropriate minimum native version requirements
4. Backup Strategy: Maintain backups of critical bundle versions

Endpoints

GET

https://api.capgo.app/bundle/

Retrieve bundle information. Returns 50 bundles per page.

查询参数

• app_id: Required. The ID of your app
• page: Optional. Page number for pagination

响应类型

interface Bundle {
  app_id: string
  bucket_id: string | null
  checksum: string | null
  created_at: string | null
  deleted: boolean
  external_url: string | null
  id: number
  minUpdateVersion: string | null
  name: string
  native_packages: Json[] | null
  owner_org: string
  r2_path: string | null
  session_key: string | null
  storage_provider: string
  updated_at: string | null
  user_id: string | null
}

请求示例

# Get all bundles
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/bundle/?app_id=app_123"

# Get next page
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/bundle/?app_id=app_123&page=1"

响应示例

{
  "data": [
    {
      "id": 1,
      "app_id": "app_123",
      "name": "1.0.0",
      "checksum": "abc123...",
      "minUpdateVersion": "1.0.0",
      "storage_provider": "r2",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "deleted": false,
      "owner_org": "org_123",
      "user_id": "user_123"
    }
  ]
}

DELETE

https://api.capgo.app/bundle/

Delete one or all bundles for an app. Use with caution as this action cannot be undone.

查询参数

For deleting a specific bundle:

interface BundleDelete {
  app_id: string
  version: string
}

For deleting all bundles:

interface BundleDeleteAll {
  app_id: string
}

请求示例s

# Delete specific bundle
curl -X DELETE \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app_123",
    "version": "1.0.0"
  }' \
  https://api.capgo.app/bundle/

# Delete all bundles
curl -X DELETE \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app_123"
  }' \
  https://api.capgo.app/bundle/

成功响应

{
  "status": "ok"
}

POST

https://api.capgo.app/bundle/

Create a new bundle with external URL.

Request Body

interface CreateBundleBody {
  app_id: string
  version: string
  external_url: string // Must be publicly accessible HTTPS URL
  checksum: string
}

请求示例

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "version": "1.2.3",
    "external_url": "https://your-storage.com/bundles/app-1.2.3.zip",
    "checksum": "a1b2c3d4e5f6789abcdef123456789abcdef123456789abcdef123456789abcd"
  }' \
  https://api.capgo.app/bundle/

成功响应

{
  "status": "ok"
}

POST (Metadata)

https://api.capgo.app/bundle/metadata

Update bundle metadata such as link and comment information.

Request Body

interface UpdateMetadataBody {
  app_id: string
  version_id: number
  link?: string
  comment?: string
}

请求示例

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app_123",
    "version_id": 456,
    "link": "https://github.com/myorg/myapp/releases/tag/v1.0.0",
    "comment": "Fixed critical bug in authentication"
  }' \
  https://api.capgo.app/bundle/metadata

成功响应

{
  "status": "success"
}

PUT

https://api.capgo.app/bundle/

Set a bundle to a specific channel. This links a bundle version to a channel for distribution.

Request Body

interface SetChannelBody {
  app_id: string
  version_id: number
  channel_id: number
}

请求示例

curl -X PUT \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app_123",
    "version_id": 456,
    "channel_id": 789
  }' \
  https://api.capgo.app/bundle/

成功响应

{
  "status": "success",
  "message": "Bundle 1.0.0 set to channel production"
}

错误处理

Common error scenarios and their responses:

// Bundle not found
{
  "error": "Bundle not found",
  "status": "KO"
}

// Invalid version format
{
  "error": "Invalid version format",
  "status": "KO"
}

// Storage error
{
  "error": "Failed to delete bundle from storage",
  "status": "KO"
}

// Permission denied
{
  "error": "Insufficient permissions to manage bundles",
  "status": "KO"
}

常见用例

1. Cleanup Old Versions

// Delete outdated beta versions
{
  "app_id": "app_123",
  "version": "1.0.0-beta.1"
}

2. App Reset

// Remove all bundles to start fresh
{
  "app_id": "app_123"
}

存储考虑因素

1. Retention Policy: Define how long to keep old bundles
2. Size Management: Monitor bundle sizes and storage usage
3. Backup Strategy: Consider backing up critical versions
4. Cost Optimization: Remove unnecessary bundles to optimize storage costs