Paquetes

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

Entendiendo los Bundles

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
• MetadatosInformación de creación, propiedad y otros datos 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 el paquete a tu almacenamiento

Cargue 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 al público a través de la URL HTTPS (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 se puede descargar el paquete (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 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álida

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 exacto 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 del Paquete: Asegura que el paquete no se haya corrompido durante el traslado
• API Verificación: Capgo verifica las sumas de comprobación antes de aceptar paquetes
• 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 Paquetes (versión): Utilice : versionamiento semántico : 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"
    }
  ]
}

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

// 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 paquetes críticos (versiones)
4. Optimización de costos: Eliminar paquetes innecesarios para optimizar los costos de almacenamiento

Sigue adelante desde Paquetes

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