Paquetes

Bundles are the core update packages in Capgo. Each bundle contains the web assets (HTML, CSS, JS) that make up your app’s content. The Bundles API allows you to manage these update packages, including listing and deleting them.

Configuración con inteligencia artificial

Un conjunto representa una versión específica del contenido web de tu aplicación y incluye:

• Conjunto (versión): Número de versión semántica para el conjunto
• Checksum: Código hash único para verificar la integridad del conjunto
• Información de almacenamiento: Detalles sobre dónde y cómo se almacena el conjunto
• Requisitos nativos: Requisitos mínimos de versión del app nativa
• Metadata: Información de creación, propiedad y otros datos de seguimiento

Creación de paquetes manual (Sin CLI)

Aquí está cómo crear y subir paquetes manualmente sin utilizar el Capgo CLI:

Paso 1: Construye tu aplicación

Primero, construye los activos web de tu aplicación:

npm run build

Paso 2: Crea paquete ZIP utilizando los mismos paquetes que Capgo CLI

Importante: Utiliza los mismos paquetes de JavaScript que Capgo CLI utiliza internamente para garantizar la compatibilidad.

Instale Paquetes Requeridos

npm install adm-zip @tomasklaen/checksum

Crear Paquete Zip con JavaScript (Igual que Capgo CLI)

Nota: En los ejemplos a continuación, version se refiere al nombre del paquete (versión) utilizado por el 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();

Paso 3: Calcular Suma de Verificación SHA256 Usando el Mismo Paquete que 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();

Step 4: Subir Paquete a Tu Almacenamiento

Sube tu archivo zip a cualquier almacenamiento accesible desde la 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: Su paquete debe ser accesible públicamente por medio de una URL HTTPS (no se requiere autenticación). Los servidores de Capgo necesitan descargar el paquete desde esta URL.

Ejemplos de URLs válidas:

• 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

Step 5: Registrar Paquete con Capgo API

Registre el paquete externo con Capgo utilizando llamadas directas 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 Parámetros

Parámetro	Descripción	Requerido
app_id	Su identificador de aplicación	Sí
version	Paquete (versión) semántica de versión (por ejemplo, “1.2.3”)	Sí
external_url	Accesible públicamente URL HTTPS donde se puede descargar el paquete (no se requiere autenticación)	Sí
checksum	Checksum SHA256 del archivo zip	Sí

Requisitos de estructura del paquete

Su archivo zip de paquete debe cumplir con estos requisitos:

1. Archivo de índice raíz: Debe tener index.html a nivel raíz
2. Capacitor Integración: Debe llamar notifyAppReady() en su aplicación code
3. Rutas de Activos: Utilice rutas relativas para todos los activos

Estructura de Paquete Válido

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

Ejemplo de Flujo de Trabajo Manual Completo

Script de Node.js simple para comprimir, calcular checksum y subir a 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);

Instale dependencias:

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

Verificación de suma de comprobación

Cálculo de suma de comprobación de JavaScript (Igual que Capgo CLI)

Utilice el paquete y método exactos que Capgo CLI utiliza 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();

Importancia de la suma de comprobación

• Integridad del paquete: Garantiza que el paquete no se ha corrompido durante el traslado
• API Verificación: Capgo verifica sumas de verificación antes de aceptar paquetes
• Verificación de Plugin: El plugin móvil verifica sumas de verificación antes de aplicar actualizaciones

Prácticas recomendadas

1. Gestión de Paquetes (versión): Utilice versiones semánticas de manera consistente
2. Optimización de almacenamiento: Elimine periódicamente paquetes no utilizados
3. Compatibilidad de Paquetes (versión): Establezca requisitos de versión nativa mínima adecuados
4. Estrategia de copia de seguridad: Mantén copias de seguridad de bundles críticos (versiones)

Endpoints

GET

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

Recupera información de bundles. Devuelve 50 bundles por página.

Parámetros de consulta

• app_id: Obligatorio. El ID de tu aplicación
• page: Opcional. Número de página para paginación

Tipo de respuesta

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
}

Solicitud de ejemplo

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

Respuesta de ejemplo

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

Eliminar

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

Elimine uno o todos los paquetes para una aplicación. Utilice con precaución ya que esta acción no se puede deshacer.

Parámetros de consulta

Para eliminar un paquete específico:

interface BundleDelete {
  app_id: string
  version: string
}

Para eliminar todos los paquetes:

interface BundleDeleteAll {
  app_id: string
}

Solicitudes de ejemplo

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

Respuesta de éxito

{
  "status": "ok"
}

POST

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

Crear un nuevo paquete con URL externa.

Cuerpo de la solicitud

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

Solicitud de ejemplo

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/

Respuesta de éxito

{
  "status": "ok"
}

POST (Metadatos)

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

Actualizar metadatos del paquete, como información de enlace y comentario.

Cuerpo de la solicitud

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

Solicitud de ejemplo

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

Respuesta de éxito

{
  "status": "success"
}

PUT

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

Establecer un conjunto de paquetes en un canal específico. Esto vincula un conjunto de paquetes (versión) a un canal para la distribución.

Cuerpo de la solicitud

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

Solicitud de ejemplo

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/

Respuesta de éxito

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

Gestión de errores

Escenarios de errores comunes y sus respuestas:

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

Uso común

1. Eliminación de paquetes antiguos (versiones)

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

2. Restauración de la aplicación

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

Consideraciones de almacenamiento

1. Política de retención: Define durante cuánto tiempo mantener paquetes antiguos
2. Gestión de tamaño: Monitorear tamaños de paquetes y uso de almacenamiento
3. Estrategia de respaldo: Considerar respaldar paquetes críticos (versiones)
4. Optimización de costos: Eliminar paquetes innecesarios para optimizar costos de almacenamiento