Procédures OAuth v2

Installation

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

Se connecter et choisir une marque

ANKK v2 utilise votre compte utilisateur via OAuth dans le navigateur. Vos droits existants s’appliquent à chaque requête. Connecter une application n’accorde aucun droit supplémentaire sur les marques. Choisissez une marque pour travailler ; l’autorisation OAuth ne sélectionne pas de marque.

Utilisez la CLI 0.5.1 avec Node.js 24 ou ultérieur. Cet identifiant public désigne ANKK CLI ; ce n’est pas un secret.

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

Remplacez les identifiants en majuscules par ceux renvoyés par vos propres requêtes. L’identifiant de connexion OAuth sélectionne votre session. Un identifiant de compte SNS désigne une cible de publication ; il diffère à la fois de la connexion OAuth et de l’identifiant de compte du fournisseur. Gardez le même environnement et la même marque tout au long de la procédure. Ces exemples précisent explicitement les deux, même si une marque par défaut est configurée localement.

Dans un terminal qui n’ouvre pas automatiquement le navigateur, utilisez ankk auth login --environment production --device --no-open et suivez les instructions de vérification affichées. Les jetons sont conservés dans le gestionnaire d’identifiants du système d’exploitation. S’il est indisponible, rétablissez-le avant de vous connecter ; ne collez jamais de jetons dans une conversation et ne les enregistrez pas dans un fichier JSON de publication.

Consulter les performances et les publications enregistrées

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

Choisissez la période réelle du rapport. Le début est inclus et la fin exclue ; les horodatages sont en UTC. Convertissez les dates locales de l’utilisateur en UTC avant la requête. Ajoutez --sns-account SNS_ACCOUNT_ID pour limiter le résultat à un compte.

Le résultat décrit des observations enregistrées. Vérifiez la couverture et les heures d’observation avant de comparer des périodes. Une donnée manquante n’est pas un zéro. Le dernier instantané d’un compte a sa propre date de mesure et ne constitue pas nécessairement le total d’une période. Les statistiques Instagram pour une période précise sont distinctes des observations accumulées. Une lecture ne lance pas de collecte auprès du fournisseur. posts refresh est une action séparée sur les données des publications et commentaires, pas une demande d’actualisation des analyses.

Les listes utilisent des curseurs. --all parcourt les pages ; les données pouvant changer pendant la pagination, le résultat n’est pas un instantané. Si un curseur expire, signalez le caractère incomplet du résultat et lancez délibérément une nouvelle liste au lieu de la fusionner silencieusement avec les anciennes pages.

Préparer un fichier avant la publication

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

La première commande enregistre et transfère le fichier. Conservez son identifiant de média même si le transfert échoue ou si la réponse est incertaine. La deuxième demande l’inspection ; utilisez le média uniquement lorsque son état final est ready. Ces étapes ne publient rien. Un média est réutilisable dans sa marque. Effectuez un téléversement distinct pour une autre marque.

Si seule l’URL de téléversement expire, utilisez media refresh-upload MEDIA_ID avec le même environnement, la même session et la même marque. La nouvelle URL ne prolonge pas l’échéance métier initiale et ne remplace pas le fichier. Des octets différents nécessitent un nouveau téléversement de média. Traitez les URL de transfert signées comme des identifiants secrets et excluez-les des transcriptions partagées. Les clients sans transfert de fichiers peuvent utiliser l’URL de progression dans le navigateur renvoyée, se connecter, choisir le fichier, puis revenir avec le même identifiant de média et vérifier qu’il est prêt.

Vérifier et publier

Confirmez la marque, les comptes, le texte intégral, l’ordre des segments du fil, les pièces jointes, les options du fournisseur et l’heure d’exécution avant de publier un contenu préparé par IA. Une approbation existante couvrant cette intention exacte suffit. Une simple demande d’analyse ou de rédaction ne vaut pas approbation de publication.

Enregistrez cette entrée minimale de publication immédiate dans publish.json. Sélectionnez un compte compatible avec la combinaison de texte et d’image proposée ; le serveur vérifie à nouveau les capacités actuelles, la disponibilité du média et les droits. Remplacez le texte anglais de l’exemple par le texte exact approuvé.

{
  "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

Choisissez et conservez une clé unique pour cette intention avant l’envoi. Réutilisez exactement cette clé et le même contenu après une réponse incertaine, y compris lors d’un passage entre API, CLI et MCP. Ne créez pas une autre publication au seul motif qu’une connexion a expiré. La même clé avec une entrée modifiée crée un conflit. Une clé expirée ne crée pas de nouveau travail : vérifiez le résultat précédent avant de lancer délibérément une nouvelle intention.

Pour une programmation, remplacez scheduled_at: null par l’heure future UTC approuvée, par exemple 2026-12-01T09:00:00Z. Remplacez cette date illustrative avant utilisation et vérifiez qu’elle reste future. Un enregistrement terminé renvoie un publish_operation_id distinct ; cela ne signifie pas que les publications SNS programmées sont publiées.

Suivre le résultat

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

Pour une publication immédiate, suivez l’identifiant d’opération renvoyé. Pour une programmation, suivez publish_operation_id à l’heure d’exécution. L’attente est facultative et locale. Le code de sortie CLI 10 indique l’expiration du délai d’attente ; le code 130 indique une interruption de l’attente. Aucun des deux n’annule la tâche serveur. Continuez à consulter la même opération. Le code 11 pendant l’attente indique un résultat final en échec, annulé ou partiellement réussi ; examinez les résultats par compte. Une consultation normale peut renvoyer le code 0 tout en signalant une opération en échec : les scripts doivent donc aussi examiner l’état dans la réponse.

Présentez chaque compte séparément. Conservez les publications réussies et leurs URL. Le tableau ordonné posts contient les publications confirmées d’un fil ; le seul post_url représentatif ne décrit pas forcément tout le fil. Une URL absente ou un état non résolu ne prouve pas que le fournisseur n’a rien créé. Gardez les résultats en cours de rapprochement ou inconnus comme non résolus jusqu’à ce que la tâche existante fournisse des preuves.

Modifier une programmation ou reprendre après un échec

Consultez contents get CONTENT_ID avec le même environnement, la même session et la même marque avant de changer le contenu ou l’heure. Transmettez sa version actuelle via --expected-version. contents update modifie les cibles admissibles non démarrées ; contents reschedule modifie leur programmation UTC. Un conflit de version exige une nouvelle lecture et une révision, pas un écrasement silencieux. contents cancel demande l’annulation ; examinez l’opération de publication renvoyée jusqu’à confirmation de l’annulation. L’exécution peut se produire avant celle-ci.

Relancez uniquement les comptes en échec sélectionnés actuellement marqués 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

Il s’agit d’une nouvelle intention d’exécution, nécessitant une nouvelle clé adaptée et l’approbation de l’utilisateur, sauf si elle est déjà couverte. Conservez cette clé de relance après une réponse incertaine. La relance utilise le contenu enregistré et s’exécute dès que possible ; elle ne republie jamais les cibles réussies ou incertaines. Pour une nouvelle programmation future, contents duplicate renvoie uniquement une entrée modifiable. Vérifiez-la et soumettez une nouvelle publication approuvée.

Écarter des entrées en échec admissibles les masque de la file de travail ; cela ne supprime pas les publications, n’efface pas l’historique d’exécution et ne relance rien. L’annulation groupée peut renvoyer des groupes acceptés et refusés ensemble ; suivez chaque opération de publication acceptée. L’exclusion groupée se termine de manière synchrone : examinez les groupes écartés et refusés du reçu, sans attendre de nouvelle opération. Dans les deux cas, lisez le reçu complet au lieu de traiter le code de sortie comme un résultat tout ou rien.

Gérer les erreurs de requête et se déconnecter

Lisez le code d’erreur structuré, l’identifiant de requête, celui d’opération lorsqu’il est disponible, next_action et retry_at. Après rétablissement de l’authentification, revenez à l’opération d’origine. Les erreurs de droits nécessitent un accès légitime, pas une autre interface. Respectez les limites de requêtes et les restrictions de capacités. Une requête pouvant être relancée n’autorise ni une nouvelle publication ni une clé de remplacement.

ankk auth logout --environment production --connection OAUTH_CONNECTION_ID

La déconnexion signale séparément la révocation serveur et la suppression des identifiants locaux. Si la révocation serveur n’est pas confirmée, révoquez l’ancienne connexion depuis les paramètres ANKK ou une autre connexion valide. Supprimer une connexion OAuth n’annule pas les publications déjà acceptées et ne supprime pas les médias appartenant à la marque.

Utiliser MCP et Skills

MCP utilise OAuth utilisateur sur https://api.ankk.app/mcp/v2. Votre hôte doit disposer d’un client enregistré ; l’URL seule ne suffit pas. Aucune inscription officielle dans les annuaires ChatGPT et Claude n’est disponible. Sans cartes, utilisez le texte et les résultats structurés. Vérifiez les valeurs et les dates d’observation, pas seulement le résumé conversationnel.

Skills fournit des procédures, sans accorder de permissions ni fournir d’identifiants. Installez le tag candidat fixe et vérifiez la marque, l’approbation et le résultat final.

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