Paquetes

Los paquetes de actualización son los paquetes de actualización centrales en Capgo. Cada paquete de actualización contiene los activos web (HTML, CSS, JS) que componen el contenido de tu aplicación. El paquete de actualización API te permite gestionar estos paquetes de actualización, incluyendo la lista y la eliminación de ellos.

Entendiendo los paquetes de actualización

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

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

Creación de Paquetes Manual (Sin CLI)

Crear y subir paquetes manualmente sin utilizar el Capgo CLI:

Paso 1: Crea tu aplicación

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

npm run build

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

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

Instala paquetes requeridos

npm install adm-zip @tomasklaen/checksum

Crear archivo 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 control SHA256 utilizando 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();

Paso 4: Subir archivo a su almacenamiento

Subir su 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"

ImportanteSu paquete debe ser accesible públicamente vía HTTPS URL (no se requiere autenticación). Los servidores de Capgo necesitan descargar el paquete desde esta URL.

Ejemplos de URLs públicas 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

Paso 5: Registra el paquete con Capgo API

Registra 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	Identificador de tu aplicación	Sí
version	Paquete (versión) Versión semántica (por ejemplo, “1.2.3”)	Sí
external_url	Accesible al público URL HTTPS donde el paquete se puede descargar (sin autenticación requerida)	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 en la raíz: Debe tener index.html en el nivel raíz
2. Integración Capacitor: Debe llamar a notifyAppReady() en su aplicación code
3. Rutas de recursos: Utilice rutas relativas para todos los activos

Estructura de Bundle Válida

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

Ejemplo Completo del Flujo de Trabajo Manual

Script de Node.js simple para comprimir, verificar 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 checksum

Calculo de Suma de Verificació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 del checksum

• Integridad del Paquete: Garantiza que el paquete no se ha corrompido durante el transferencia
• API Verificación: Capgo verifica sumas de verificación antes de aceptar paquetes
• Verificación de PluginLa aplicación móvil verifica las sumas de comprobación antes de aplicar actualizaciones.

Prácticas recomendadas

1. Gestión de paquetes (versión): Utilice numerosación semántica consistentemente
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/

Obtén información de bundle. 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 paquete en un canal específico. Esto vincula un paquete (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
  target?: "auto" | "stable" | "rollout" // default: auto
}

target donde se vincula el paquete cuando el canal tiene configurada la distribución progresiva:

• auto — objetivo de lanzamiento cuando se configura el lanzamiento progresivo; estable en caso contrario (predeterminado).
• rollout — siempre establecer el objetivo de distribución; fallback estable sin cambios.
• stable — reemplazar fallback estable (paso de escape).

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

Casos de uso comunes

1. Eliminar versiones antiguas de los paquetes

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

2. App Reset

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

Consideraciones de almacenamiento

1. Política de retenciónDefine cuánto tiempo mantener los paquetes antiguos
2. Gestión de tamaño: Monitor bundle sizes and storage usage
3. Estrategia de respaldo: Consider backing up críticas paquetes (versiones)
4. Optimización de Costos: Elimine paquetes innecesarios para optimizar costos de almacenamiento

Continúe desde Paquetes

Si está utilizando Paquetes para planificar el almacenamiento y el manejo de archivos, conecte con @capgo/capacitor-almacenamiento-de-datos-sqlite para la implementación detallada en @capgo/capacitor-almacenamiento-de-datos-sqlite Usando @capgo/capacitor-almacenamiento-de-datos-sqlite para la capacidad nativa en Usando @capgo/capacitor-almacenamiento-de-datos-sqlite @capgo/capacitor-archivo para el detalle de implementación en @capgo/capacitor-archivo Usando @capgo/capacitor-archivo para la capacidad nativa en Usando @capgo/capacitor-archivo, y @capgo/capacitor-subidor para el detalle de implementación en @capgo/capacitor-subidor.