Commet 5.0 — API Headless

Commet ahora es completamente headless. Todo lo que podés hacer en el dashboard, ahora lo podés hacer desde el SDK. v5 se publica en los cinco lenguajes con los mismos recursos, métodos y tipos.

Nuevos recursos

Antes eran solo desde el dashboard. Ahora los podés manejar programáticamente:

• Plans — crear, actualizar, eliminar, gestionar features y precios, visibilidad, precios regionales
• Invoices — listar, ver detalle, descargar PDF, enviar al cliente, actualizar estado, crear ajustes
• Transactions — listar, ver detalle, reembolsar, reintentar pagos fallidos
• Plan Groups — organizar planes en grupos, reordenar, gestionar membresía
• Promo Codes — crear y gestionar códigos de descuento
• Credit Packs — crear y gestionar paquetes de créditos
• API Keys — crear, listar, eliminar keys programáticamente
• Webhooks — crear, listar, eliminar endpoints y disparar envíos de prueba
• Addons — CRUD completo para definiciones de addons, más activar/desactivar en una suscripción

Recursos existentes también tienen métodos nuevos:

• Subscriptions — list(), previewChange(), activateAddon(), deactivateAddon(), adjustBalance(), topupBalance(), purchaseCredits()
• Features — create(), update(), delete()

Firmas de métodos más simples

seatType → featureCode

Los seats son features. El nombre del parámetro ahora lo refleja.

// v4
commet.seats.add({ customerId: userId, seatType: "member", count: 1 });

// v5
commet.seats.add({ customerId: userId, featureCode: "member" });

count tiene default 1 — no hace falta pasarlo para operaciones de un solo seat.

subscriptions.get() → getActive()

El nombre ahora dice lo que hace.

// v4
const sub = await commet.subscriptions.get(userId);

// v5
const sub = await commet.subscriptions.getActive({ customerId: userId });

Sin más customer() context

Todos los métodos ahora reciben customerId como parámetro directo. Menos indirección, más fácil de entender.

// v4
const customer = commet.customer(userId);
await customer.features.canUse("editor");
await customer.seats.add("member");

// v5
await commet.features.canUse({ customerId: userId, code: "editor" });
await commet.seats.add({ customerId: userId, featureCode: "member" });

externalId eliminado

Si estabas pasando externalId para identificar clientes en seats, usage o subscriptions — usá customerId. Para crear un customer, seguí usando id.

// v4 — externalId en varios recursos
commet.usage.track({ feature: "api_calls", externalId: userId });

// v5 — customerId en todos lados
commet.usage.track({ feature: "api_calls", customerId: userId });

Mejores detalles de error

Los errores de la API ahora incluyen type, param y doc_url cuando están disponibles, para que puedas construir mejor manejo de errores.

try {
  await commet.subscriptions.create({ customerId, planCode: "pro" });
} catch (error) {
  if (error instanceof CommetAPIError) {
    console.log(error.type);    // "invalid_request_error"
    console.log(error.param);   // "planCode"
    console.log(error.docUrl);  // link a la documentación
  }
}

Modo debug

Pasá debug: true para ver cada request y response en tu consola. Útil cuando estás integrando.

const commet = new Commet({ apiKey: "ck_...", debug: true });
// [Commet SDK] POST https://commet.co/api/v1/subscriptions
// [Commet SDK] Response status: 201 Created

CLI con resource commands

Cada método del SDK ahora disponible desde la terminal. Sin escribir código — creá clientes, planes, suscripciones, emití reembolsos, todo desde la línea de comandos.

commet customers create --email user@example.com --id user_123
commet plans create --name "Pro" --code pro
commet plans add-price --plan-id pln_abc --billing-interval monthly --price 2900
commet subscriptions create --customer-id user_123 --plan-code pro
commet invoices list --customer-id user_123
commet transactions refund --id txn_abc

15 recursos, 86 comandos. Misma estructura en todos: commet <recurso> <acción> [--flags].

--output agent devuelve JSON crudo. --help en cada nivel muestra las acciones y flags disponibles. Los errores siempre te dicen qué salió mal y qué valores son válidos.

commet link ahora auto-genera una API key para tu org — sin pasos extra.

5 SDKs, misma API

Node, Python, Go, Java y PHP — todos en v5.0.0, todos con los mismos 15 recursos y firmas de métodos idénticas.

npm install @commet/node@5
pip install commet-sdk==5.0.0
go get github.com/commet-labs/commet-go/v5
composer require commet/commet-php:^5.0
implementation("co.commet:commet-java:5.0.0") // Gradle