Bundle

インストール手順と、このプラグインの完全なMarkdownガイドを含むセットアッププロンプトをコピーします。

Capgo において、Bundle はアップデートの核となるパッケージです。各 Bundle には、アプリのコンテンツを構成する Web アセット（HTML、CSS、JS）が含まれています。Bundles API を使用すると、Bundle の一覧表示や削除など、これらのアップデートパッケージを管理できます。

Bundle の理解

Bundle はアプリの Web コンテンツの特定のバージョンを表し、以下の内容を含みます：

Bundle (バージョン): セマンティックバージョン番号 Bundle 用の
チェックサム: bundleの整合性を検証する一意のハッシュ
ストレージ情報: bundleの保存場所と保存方法の詳細
ネイティブ要件: ネイティブアプリの最小バージョン要件
メタデータ: 作成日時、所有権、その他の追跡情報

手動でのbundle作成（CLIを使用しない場合）

Capgo CLI を使用せずに、手動でbundleを作成してuploadする方法は次のとおりです:

ステップ 1: アプリのビルド

まず、アプリの Web アセットをビルドしてください：

npm run build

ステップ 2: Capgo CLI と同じパッケージで Bundle Zip を作成

重要: 互換性を確保するため、Capgo CLI が内部で使用している JavaScript パッケージとまったく同じものを使用してください。

必要なパッケージのインストール

npm install adm-zip @tomasklaen/checksum

JavaScriptでZip Bundleを作成する (Capgo CLI と同様)

注意: 以下の例では、 version は API で使用される bundle (version) 名を指します。

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 をアップロード

zip ファイルを Web からアクセス可能な任意のストレージに upload してください:

# 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"

重要: バンドルは以下の条件を満たす必要があります： 公開アクセス可能であること HTTPS URL経由でアクセスできること（認証不要）。Capgo のサーバーがこのURLからバンドルをダウンロードします。

有効な公開URLの例：

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 を登録

直接 API を呼び出して、外部バンドルを Capgo に登録します：

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 パラメータ

パラメータ	説明	必須
`app_id`	アプリの識別子	はい
`version`	Bundle (バージョン) セマンティックバージョン (例: “1.2.3”)	はい
`external_url`	公開アクセス可能 BundleをダウンロードできるHTTPS URL (認証不要)	はい
`checksum`	zipファイルのSHA256チェックサム	はい

Bundle の構造要件

bundleのzipファイルは以下の要件を満たす必要があります：

ルートインデックスファイル：必ず含める index.html ルートレベルに
Capacitor の統合：呼び出しが必要 notifyAppReady() アプリ内で code を
アセットパスすべての資産には相対パスを使用してください

有効な Bundle 構造

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

手動ワークフローの完全な例

zip圧縮、チェックサム作成、Capgoへのアップロードを行うシンプルなNode.jsスクリプト:

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);

依存関係のインストール:

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

チェックサムの検証

JavaScript によるチェックサム計算 (Capgo CLI と同様)

Capgo CLI が内部で使用しているものと全く同じパッケージおよびメソッドを使用してください：

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の整合性: 転送中にbundleが破損していないことを保証します
API による検証: Capgo はbundleを受け入れる前にchecksumを検証します
Pluginの検証: モバイルプラグインがアップデート適用前にチェックサムを検証します

ベストプラクティス

Bundle (version) 管理: 使用するセマンティックバージョニング一貫して
ストレージの最適化: 未使用のbundleを定期的に削除する
Bundle (version) の互換性: 適切な最小Native Buildバージョン要件を設定する
バックアップ戦略: 重要なbundle（バージョン）のバックアップを保持します

エンドポイント

GET

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

bundle情報を取得します。フィルタなしの場合、1ページあたり50件のbundleを返します。フィルタを version または id使用した場合は、0件または1件のbundleを含む同じJSON配列形式で返されます。

クエリパラメータ

app_id: 必須。アプリのID
page: 任意。ページネーション用のページ番号（ version または id が設定されています)
version: オプション。正確なbundleバージョン名 ("app_versions.name, 例えば 1.2.3)。0個または1個の要素を含むJSON配列を返します。
id: オプション。数値のbundle ID ("app_versions.id)。0個または1個の要素を含むJSON配列を返します。

同じ authorization ヘッダーと API キーによるapp scoping を使用してください。query-schemaバリデーションで拒否された値は、 invalid_query エラー。

バージョンが存在するか確認する (CI)

CLI の代わりに HTTP チェックが必要な場合は、upload や channel の割り当て前にこれを使用してください：

curl -H "authorization: YOUR_API_KEY" \
  "https://api.capgo.app/bundle/?app_id=com.example.app&version=1.2.3"

JSON 配列が空でない場合は、そのバージョンが既にアプリに存在することを意味します。空の場合は存在しません。

upload ワークフローでは、Capgo の CLI フラグが bundle upload --version-exists-ok 対象のバージョンが既に存在する場合、このエンドポイントを呼び出さなくても CI ジョブは正常に終了します。

レスポンスタイプ

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"

# Look up one bundle by version name
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/bundle/?app_id=app_123&version=1.0.0"

# Look up one bundle by id
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/bundle/?app_id=app_123&id=456"

レスポンス例

[
  {
    "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"
  }
]

削除

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

アプリのbundleを単一または一括で削除します。この操作は取り消せないため、実行には十分注意してください。

クエリパラメータ

特定のbundleを削除する場合：

interface BundleDelete {
  app_id: string
  version: string
}

すべてのbundleを削除する場合：

interface BundleDeleteAll {
  app_id: string
}

リクエスト例

# 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/

外部URLを使用して新しいbundleを作成します。

リクエストボディ

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 (メタデータ)

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

リンクやコメント情報などの bundle メタデータを更新します。

リクエストボディ

interface UpdateMetadataBody {
  app_id: string
  version_id: number // bundle (version) id
  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/

特定のチャンネルにbundleを割り当てます。これにより、配布用にbundle（バージョン）とチャンネルが紐付けられます。

リクエストボディ

interface SetChannelBody {
  app_id: string
  version_id: number // bundle (version) id
  channel_id: number
  target?: "auto" | "stable" | "rollout" // default: auto
}

target progressive rolloutが設定されている場合、チャンネルに紐付けられるbundleの場所を制御します：

auto — progressive rollout設定時はrollout target、それ以外はstable（デフォルト）。
rollout — 常にrollout targetを設定します。stable fallbackは変更されません。
stable — stable fallbackを置き換えます（エスケープハッチ）。

リクエスト例

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"
}

エラーハンドリング

すべてのエラーは、以下で説明する標準エラー形式に従います API の概要.

よくあるエラーシナリオとそのレスポンス：

// app_id is not a reverse-domain identifier
{
  "error": "invalid_app_id",
  "message": "App ID must be a reverse domain string",
  "moreInfo": { "app_id": "my app" }
}

// Deleting a bundle without access to the app
{
  "error": "cannot_delete_bundle",
  "message": "You can't access this app",
  "moreInfo": { "app_id": "com.example.app" }
}

// Deleting a bundle that a channel still uses
{
  "error": "cannot_delete_linked_version",
  "message": "Cannot delete a bundle linked to a channel",
  "moreInfo": { "app_id": "com.example.app", "version": "1.0.0" }
}

// Creating a bundle whose version is not valid semver
{
  "error": "invalid_version_format",
  "message": "Version must be valid semver format (e.g., 1.0.0, 1.0.0-alpha.1)",
  "moreInfo": { "version": "v1" }
}

// Setting a channel to a bundle that does not exist
{
  "error": "cannot_find_version",
  "message": "Cannot find version",
  "moreInfo": {}
}

よくあるユースケース

古いBundle（バージョン）のクリーンアップ

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

アプリのリセット

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

ストレージの考慮事項

保持ポリシー: 古いbundleの保持期間を定義します
サイズ管理: bundleのサイズとストレージ使用量を監視します
バックアップ戦略: 重要なbundle（バージョン）のバックアップを検討してください
コスト最適化: 不要なbundleを削除してストレージコストを最適化する

Bundles から続ける

使用している場合 Bundle ストレージとファイル処理を計画するには、以下と連携してください： @capgo/capacitor-data-storage-sqlite @capgo/capacitor-data-storage-sqlite の実装の詳細については、 @capgo/capacitor-data-storage-sqlite の使い方「@capgo/capacitor-data-storage-sqliteの使用方法」におけるネイティブ機能について、 @capgo/capacitor-file @capgo/capacitor-file の実装の詳細については、 @capgo/capacitor-file の使い方「@capgo/capacitor-file の使用」のネイティブ機能については、および @capgo/capacitor-uploader @capgo/capacitor-uploader. の実装の詳細については