Paquetes

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

Entendiendo los paquetes de actualización

Un paquete 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
• MetadatosTiempo de creación, propiedad y otra información de seguimiento

Creación de paquetes manual (Sin CLI)

Esto es 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 archivo zip de paquete utilizando los mismos paquetes que Capgo CLI

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

Instale los 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 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 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"

Importantecontexto: Página/área: Página de programa de recompensa de bugs. Rol: Etiqueta de interfaz de usuario. Visto en: página bug-bounty.astro. Clave de mensaje `bug_bounty_important_label` (Etiqueta importante de recompensa de bugs). : Tu paquete debe ser via HTTPS URL (no authentication required). Capgo’s servers need to download the bundle from this URL.

por medio de una URL HTTPS (no se requiere autenticación). Los servidores de __CAPGO_KEEP_0__ necesitan descargar el paquete desde esta 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

Step 5: Register Bundle with 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 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 tu aplicación code
3. Rutas de Recursos: Utilice rutas relativas para todos los recursos

Estructura de Paquete Válido

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

Ejemplo Completo del Flujo 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);

Instalar dependencias:

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

Verificación de checksum

Cálculo de checksum de JavaScript (Igual que Capgo CLI)

Utilice el mismo paquete y método 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 checksum

• Integridad de la Colección: Asegura que la colección no haya sido dañada durante el traslado
• API Verificación: Capgo verifica las sumas de comprobación antes de aceptar colecciones
• Verificación de Plugin: El plugin móvil verifica las sumas de comprobación antes de aplicar actualizaciones

Prácticas Recomendadas

1. Gestión de Colección (versión): Utilice la numeración semántica 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ínimos adecuados
4. Estrategia de Copia de Seguridad: Mantenga copias de seguridad de paquetes críticos (versiones)

Puntos de Acceso

GET

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

Recupere información de paquetes. Devuelve 50 paquetes 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"
    }
  ]
}

BORRAR

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

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
}

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 versiones antiguas de los paquetes (Bundles)

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

2. Reset de la aplicación

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

Consideraciones de almacenamiento

1. Política de retención: Define cuánto tiempo mantener los paquetes antiguos
2. Gestión de tamaño: Monitorear los tamaños de los paquetes y el uso de almacenamiento
3. Estrategia de Copia de Seguridad: Considerar la copia de seguridad de los bundles críticos (versiones)
4. Optimización de Costos: Eliminar bundles innecesarios para optimizar los costos de almacenamiento

Continuar desde Bundles

Si estás utilizando Bundles para planificar el almacenamiento y el manejo de archivos, conecta con sqlite-data-storage-@capgo/capacitor para los detalles de implementación en sqlite-data-storage-@capgo/capacitor Usando sqlite-data-storage-@capgo/capacitor 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.