Paquetes

Los paquetes de actualización son los paquetes de actualización básicos en Capgo. Cada paquete de actualización contiene los activos web (HTML, CSS, JS) que componen el contenido de tu aplicación. Los paquetes de actualización API te permiten 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:

• Versión del paquete: Número de versión semántica para el paquete de actualización
• Checksum: Código hash único para verificar la integridad del paquete
• Storage Info: Detalles sobre dónde y cómo se almacena el paquete
• Native Requirements: 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 manual de paquetes (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 archivo ZIP de paquetes utilizando los mismos paquetes que Capgo CLI

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

Instalar 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 checksum 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 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 a través de una 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	Su identificador de 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 de 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 a notifyAppReady() en su aplicación code
3. Rutas de Recursos: Utilice rutas relativas para todos los activos

Estructura de paquete 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

Cálculo de Sumas de Verificación de JavaScript (Igual que Capgo CLI)

Utilice el paquete y el 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 Verificación

• Integridad del Paquete: Garantiza que el paquete no se ha corrompido durante la transferencia
• API Verificación: Capgo verifica sumas de verificación antes de aceptar paquetes
• Verificación del Plugin: Verifica los checksums antes de aplicar actualizaciones

Prácticas recomendadas

1. Gestión de paquetes (versión): Utilice versión semántica de manera consistente Optimización de almacenamiento
2. : Elimine paquetes innecesarios periódicamenteCompatibilidad de paquetes (versión)
3. : Establezca requisitos de versión nativa mínimos adecuadosEstrategia de respaldo
4. __CAPGO_KEEP_0__: Mantén copias de seguridad de bundles críticos (versiones)

Endpoints

GET

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

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

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

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-de-datos-sqlite, @capgo/capacitor-archivo para los detalles 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.