Bundle

I pacchetti sono i pacchetti di aggiornamento principali in Capgo. Ogni pacchetto contiene gli asset web (HTML, CSS, JS) che compongono il contenuto dell'applicazione. I pacchetti API consente di gestire questi pacchetti di aggiornamento, inclusa la visualizzazione e la cancellazione di essi.

Capire i pacchetti

Un pacchetto rappresenta una versione specifica del contenuto web dell'app e include:

• Pacchetto (versione): Numero di versione semantico per il pacchetto
• Checksum: Hash univoca per verificare l'integrità del pacchetto
• Informazioni di archiviazione: Dettagli su dove e come il pacchetto è archiviato
• Requisiti nativi: Requisiti minimi di versione per l'app nativa
• Metadati: Informazioni di creazione, proprietà e altre informazioni di tracciamento

Creazione del Pacchetto Manuale (Senza CLI)

Ecco come creare e caricare manualmente i pacchetti senza utilizzare il Capgo CLI:

Passo 1: Costruisci l'App

Innanzitutto, costruisci gli asset web dell'app:

npm run build

Passo 2: Crea Pacchetto Zip Utilizzando gli Stessi Pacchetti di Capgo CLI

Importante: Utilizza gli stessi pacchetti JavaScript esatti che Capgo CLI utilizza internamente per garantire la compatibilità.

Installare Pacchetti Richiesti

npm install adm-zip @tomasklaen/checksum

Creare Bundle Zip con JavaScript (Lo stesso di Capgo CLI)

Nota: Nelle esempi che seguono, version si riferisce al nome del bundle (versione) utilizzato dal API.

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

Passo 3: Calcolare Checksum SHA256 Utilizzando lo Stesso Pacchetto di 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;
}

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

main();

Passo 4: Carica il pacchetto nel tuo archivio

Carica il tuo file zip in qualsiasi archivio accessibile da web:

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

Importante: Il tuo pacchetto deve essere accessibile al pubblico attraverso l'URL HTTPS (nessuna autenticazione richiesta). I server di Capgo devono scaricare il pacchetto da questo URL.

Esempi di URL pubblici validi:

• 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

Passo 5: Registra il pacchetto con Capgo API

Registra il bundle esterno con Capgo utilizzando chiamate dirette API:

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 Parametri

Parametro	Descrizione	Obbligatorio
app_id	Il tuo identificativo dell'app	Sì
version	Bundle (versione) semantic version (ad esempio, “1.2.3”)	Sì
external_url	Accessibile al pubblico URL HTTPS dove il bundle può essere scaricato (nessuna autenticazione richiesta)	Sì
checksum	Checksum SHA256 del file zip	Sì

Requisiti di struttura del bundle

Il tuo file zip del bundle deve rispettare questi requisiti:

1. File di indice radice: Deve avere index.html al livello radice
2. Capacitor Integrazione: Deve chiamare notifyAppReady() in tua app code
3. Periferiche di Asset: Utilizza percorsi relativi per tutte le risorse

Struttura Bundle Valida

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

Esempio completo del Flusso di Lavoro Manuale

Script di Node.js semplice per zip, checksum e caricare su 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);

Installa le dipendenze:

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

Verifica del checksum

Calcolo del checksum JavaScript (Lo stesso di Capgo CLI)

Usa lo stesso pacchetto e metodo che Capgo CLI utilizza internamente:

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

Importanza del checksum

• Integrità del pacchetto: Assicura che il pacchetto non sia stato corrotto durante il trasferimento
• API VerificaCapgo verifica i checksum prima di accettare i pacchetti
• Verifica Plugin__CAPGO_KEEP_0__ verifica i checksum prima di applicare gli aggiornamenti

Pratiche Raccomandate

1. Gestione Pacchetti (versione)Utilizzare la versioning semantico in modo coerente
2. Optimizzazione del StorageEliminare i pacchetti inutilizzati periodicamente
3. Compatibilità Pacchetti (versione)Impostare le richieste di versione nativa minima appropriate
4. Strategia di Backup: Mantieni backup dei bundle critici (versioni)

Endpoint

GET

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

Recupera informazioni sui bundle. Restituisce 50 bundle per pagina.

Parametri di query

• app_id: Obbligatorio. L'ID del tuo app
• page: Facoltativo. Numero di pagina per la paginazione

Tipo di Risposta

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
}

Esempio di richiesta

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

Esempio di risposta

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

Cancella

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

Elimina uno o tutti i pacchetti per un'app. Utilizza con cautela poiché questa azione non può essere annullata.

Parametri di query

Per eliminare un bundle specifico:

interface BundleDelete {
  app_id: string
  version: string
}

Per eliminare tutti i bundle:

interface BundleDeleteAll {
  app_id: string
}

Richieste di Esempio

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

Risposta di Successo

{
  "status": "ok"
}

POST

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

Crea un nuovo bundle con URL esterna.

Corpo della richiesta

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

Esempio di richiesta

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/

Risposta di successo

{
  "status": "ok"
}

POST (Metadati)

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

Aggiorna i metadati del pacchetto, ad esempio informazioni di collegamento e commento.

Corpo della richiesta

interface UpdateMetadataBody {
  app_id: string
  version_id: number // bundle (version) id
  link?: string
  comment?: string
}

Esempio di richiesta

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

Risposta di successo

{
  "status": "success"
}

PUT

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

Imposta un bundle in un canale specifico. Questo collega un bundle (versione) a un canale per la distribuzione.

Corpo della richiesta

interface SetChannelBody {
  app_id: string
  version_id: number // bundle (version) id
  channel_id: number
}

Esempio di richiesta

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/

Risposta di Successo

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

Gestione degli Errori

Scenari di errore comuni e relative risposte:

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

// Invalid bundle (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"
}

Casi d'uso comuni

1. Pulizia delle vecchie bundle (versioni)

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

2. Reset dell'app

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

Considerazioni di archiviazione

1. Politica di conservazione: Definisci per quanto tempo conservare i vecchi pacchetti
2. Gestione delle dimensioni: Monitora le dimensioni dei pacchetti e l'uso dello spazio di archiviazione
3. Strategia di backup: Considera di effettuare un backup dei pacchetti critici (versioni)
4. Optimizzazione dei costi: Elimina i pacchetti non necessari per ottimizzare i costi di archiviazione