Flujos de trabajo con OAuth v2

Instalación

npm install --global @anakonn/ankk@0.5.1
ankk --version

Inicia sesión y elige una marca

ANKK v2 usa tu cuenta de usuario mediante OAuth en el navegador. Tus permisos existentes se aplican a cada solicitud. Conectar una aplicación no otorga permisos adicionales sobre marcas. Elige una marca al trabajar; la autorización OAuth no selecciona una marca.

Usa CLI 0.5.1 con Node.js 24 o posterior. El ID de cliente público identifica ANKK CLI; no es un secreto.

export ANKK_OAUTH_CLIENT_ID=ankk-cli-production

ankk --json auth login --environment production
ankk auth status --environment production --connection OAUTH_CONNECTION_ID
ankk --json brands list --environment production --connection OAUTH_CONNECTION_ID --all
ankk --json connections list --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --all

Reemplaza los identificadores en mayúsculas con los ID devueltos por tus propias solicitudes. El ID de conexión OAuth selecciona tu inicio de sesión. Un ID de cuenta SNS identifica el destino de publicación; es distinto tanto de la conexión OAuth como del ID de cuenta del proveedor. Usa el mismo entorno y la misma marca durante todo el procedimiento. Estos ejemplos especifican ambos explícitamente, incluso si configuraste una marca predeterminada local.

En una terminal que no abra el navegador automáticamente, usa ankk auth login --environment production --device --no-open y sigue las instrucciones de verificación que aparecen. Los tokens se guardan en el almacén de credenciales del sistema operativo. Si no está disponible, restáuralo antes de iniciar sesión; nunca pegues tokens en un chat ni los guardes en un archivo JSON de publicación.

Consulta el rendimiento y las publicaciones almacenadas

ankk --json analytics get --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --from 2026-10-01T00:00:00Z --to 2026-10-02T00:00:00Z
ankk --json posts list --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --all

Elige el período real del informe. El inicio está incluido y el final excluido; las marcas de tiempo usan UTC. Convierte las fechas locales del usuario a UTC antes de consultar. Agrega --sns-account SNS_ACCOUNT_ID para limitar el resultado a una cuenta.

El resultado describe observaciones almacenadas. Revisa la cobertura y los momentos de observación antes de comparar períodos. Los datos faltantes no equivalen a cero. La instantánea más reciente de una cuenta tiene su propio momento de medición y no necesariamente representa el total de un período. Las estadísticas de un período exacto de Instagram son distintas de las observaciones acumuladas. Una lectura no inicia la recopilación del proveedor. posts refresh es una acción separada para datos de publicaciones y comentarios, no una solicitud para actualizar el análisis.

Las listas usan cursores. --all recorre las páginas; los datos pueden cambiar durante la paginación, por lo que el resultado no es una instantánea. Si un cursor vence, informa que el resultado está incompleto e inicia deliberadamente una nueva consulta de lista, en lugar de combinarla silenciosamente con las páginas anteriores.

Prepara un archivo antes de publicar

ankk --json media create-upload --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --file ./photo.jpg --idempotency-key UPLOAD_KEY
ankk --json media complete-upload MEDIA_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --idempotency-key INSPECTION_KEY --wait --wait-timeout 180
ankk --json media get MEDIA_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID

El primer comando registra y transfiere el archivo. Guarda su ID de medio aunque la transferencia falle o la respuesta sea incierta. El segundo solicita la inspección; usa el medio solo cuando su estado final sea ready. Estos pasos no publican. Puedes reutilizar medios dentro de su marca. Para otra marca, realiza una carga separada.

Si solo vence la URL de carga, usa media refresh-upload MEDIA_ID con el mismo entorno, inicio de sesión y marca. La nueva URL no extiende el plazo original del proceso ni reemplaza el archivo. Un contenido binario diferente requiere una nueva carga de medio. Trata las URL de transferencia firmadas como credenciales y no las incluyas en transcripciones compartidas. Los clientes sin transferencia de archivos pueden usar la URL de progreso en el navegador devuelta, iniciar sesión, seleccionar el archivo y regresar con el mismo ID de medio para comprobar que esté listo.

Revisa y publica

Confirma la marca, las cuentas, el texto completo, el orden de los segmentos del hilo, los archivos adjuntos, las opciones del proveedor y el momento de ejecución antes de publicar contenido preparado por IA. Una aprobación existente para esa intención exacta es suficiente. Una solicitud únicamente de análisis o redacción no es una aprobación para publicar.

Guarda esta entrada mínima de publicación inmediata como publish.json. Selecciona una cuenta compatible con la combinación propuesta de texto e imagen; el servidor vuelve a comprobar las capacidades actuales, la preparación del medio y los permisos. Reemplaza el texto en inglés del ejemplo con el texto exacto aprobado.

{
  "scheduled_at": null,
  "targets": [
    {
      "sns_account_id": "SNS_ACCOUNT_ID",
      "text": "The exact text you approved",
      "media_ids": ["MEDIA_ID"]
    }
  ]
}

ankk --json contents publish --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --file publish.json --idempotency-key PUBLICATION_KEY

Antes de enviar, elige y conserva una clave única para esta intención. Reutiliza exactamente esa clave y el mismo contenido después de una respuesta incierta, incluso al cambiar entre API, CLI y MCP. No crees otra publicación solo porque una conexión agotó el tiempo de espera. La misma clave con una entrada modificada genera un conflicto. Una clave vencida no crea trabajo nuevo: revisa el resultado anterior antes de iniciar deliberadamente una nueva intención.

Para programar, reemplaza scheduled_at: null con la hora futura en UTC aprobada, por ejemplo 2026-12-01T09:00:00Z. Sustituye esta fecha ilustrativa antes de usarla y verifica que siga siendo futura. Un registro completado devuelve un publish_operation_id separado; no significa que las publicaciones SNS programadas ya se hayan publicado.

Sigue el resultado

ankk --json operations get OPERATION_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --wait --wait-timeout 180

Para una publicación inmediata, sigue el ID de operación devuelto. Para una programación, sigue publish_operation_id al momento de ejecución. La espera es opcional y local. El código de salida 10 de la CLI significa que venció el límite de espera; el 130, que se interrumpió la espera. Ninguno cancela la tarea del servidor. Continúa consultando la misma operación. El código 11 al esperar indica un resultado final fallido, cancelado o parcialmente exitoso; revisa los resultados por cuenta. Una consulta normal de estado puede terminar con código 0 mientras informa una operación fallida, por lo que los scripts también deben revisar el estado de la respuesta.

Informa cada cuenta por separado. Conserva las publicaciones exitosas y sus URL. El arreglo ordenado posts contiene las publicaciones confirmadas de un hilo; el post_url representativo por sí solo puede no describir todo el hilo. La ausencia de una URL o un estado sin resolver no demuestra que el proveedor no haya creado nada. Mantén sin resolver los resultados en conciliación o desconocidos hasta que la tarea existente aporte evidencia.

Cambia una programación o recupera un fallo

Consulta contents get CONTENT_ID con el mismo entorno, inicio de sesión y marca antes de modificar el contenido o la hora. Envía su versión actual como --expected-version. contents update edita los destinos elegibles que aún no comenzaron; contents reschedule cambia su horario UTC. Un conflicto de versión requiere una nueva lectura y revisión, no una sobrescritura silenciosa. contents cancel solicita la cancelación; revisa la operación de publicación devuelta hasta confirmar la cancelación. La ejecución podría adelantarse.

Reintenta solo las cuentas fallidas seleccionadas que actualmente estén marcadas con can_retry:

ankk --json contents retry ORIGINAL_OPERATION_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --accounts FAILED_SNS_ACCOUNT_ID --idempotency-key RETRY_KEY

Esta es una nueva intención de ejecución y requiere una nueva clave adecuada y aprobación del usuario, salvo que ya esté cubierta. Conserva esa clave de reintento si la respuesta es incierta. El reintento usa contenido almacenado y se ejecuta lo antes posible; nunca vuelve a publicar destinos exitosos o inciertos. Para una nueva programación futura, contents duplicate solo devuelve una entrada editable. Revísala y envía una nueva publicación aprobada.

Descartar entradas fallidas elegibles de la cola las oculta de la cola de trabajo; no elimina publicaciones, borra el historial de ejecución ni reintenta nada. La cancelación masiva puede devolver grupos aceptados y rechazados a la vez; sigue cada operación de publicación aceptada. El descarte masivo se completa sincrónicamente: revisa los grupos descartados y rechazados del comprobante, sin esperar una nueva operación. En ambos casos, lee el comprobante completo en lugar de interpretar el código de salida como un resultado de todo o nada.

Gestiona errores de solicitud y desconéctate

Lee el código de error estructurado, el ID de solicitud, el ID de operación cuando esté disponible, next_action y retry_at. Tras recuperar la autenticación, regresa a la operación original. Los errores de permisos requieren acceso legítimo, no una interfaz diferente. Respeta los límites de solicitudes y las restricciones de capacidades. Una solicitud reintentable no autoriza una nueva publicación ni una clave de reemplazo.

ankk auth logout --environment production --connection OAUTH_CONNECTION_ID

El cierre de sesión informa por separado la revocación en el servidor y la eliminación de credenciales locales. Si la revocación del servidor no está confirmada, revoca la conexión anterior desde la configuración de ANKK u otra conexión válida. Eliminar una conexión OAuth no cancela publicaciones ya aceptadas ni elimina medios pertenecientes a la marca.

Usa MCP y Skills

MCP usa OAuth de usuario en https://api.ankk.app/mcp/v2. Tu host necesita un cliente registrado; la URL por sí sola no completa la conexión. No hay publicaciones oficiales en los directorios de ChatGPT y Claude. Si no hay tarjetas, usa los resultados de texto y estructurados. Verifica los valores y las fechas de observación, no solo el resumen de la conversación.

Skills ofrece procedimientos, no permisos ni credenciales. Instala la etiqueta candidata fija y verifica la marca, la aprobación y el resultado final.

npx skills add https://github.com/Anakonn/ankk-skills/tree/v0.1.0-rc.1 --skill ankk-analyze --skill ankk-publish