Alur kerja OAuth v2

Instalasi

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

Masuk dan pilih merek

ANKK v2 menggunakan akun pengguna Anda melalui OAuth berbasis browser. Izin Anda yang sudah ada berlaku pada setiap permintaan. Menghubungkan aplikasi tidak memberikan izin merek tambahan. Pilih merek saat bekerja; otorisasi OAuth tidak memilih merek.

Gunakan CLI 0.5.1 dengan Node.js 24 atau lebih baru. ID klien publik mengidentifikasi ANKK CLI; ini bukan rahasia.

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

Ganti pengenal huruf besar dengan ID yang dikembalikan oleh permintaan Anda sendiri. ID koneksi OAuth memilih sesi masuk Anda. ID akun SNS mengidentifikasi tujuan publikasi; ID ini berbeda dari koneksi OAuth maupun ID akun milik penyedia. Gunakan lingkungan dan merek yang sama sepanjang alur kerja. Contoh ini menetapkan keduanya secara eksplisit, sekalipun Anda telah mengatur merek default secara lokal.

Jika terminal tidak membuka browser secara otomatis, gunakan ankk auth login --environment production --device --no-open dan ikuti petunjuk verifikasi yang ditampilkan. Token disimpan dalam penyimpanan kredensial OS. Jika penyimpanan itu tidak tersedia, pulihkan sebelum masuk; jangan pernah menempelkan token ke percakapan atau menyimpannya dalam berkas JSON publikasi.

Baca kinerja dan postingan tersimpan

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

Pilih periode pelaporan yang sebenarnya. Waktu mulai termasuk dan waktu akhir tidak termasuk; stempel waktu menggunakan UTC. Ubah tanggal lokal pengguna menjadi UTC sebelum melakukan kueri. Tambahkan --sns-account SNS_ACCOUNT_ID untuk membatasi hasil ke satu akun.

Hasil menjelaskan pengamatan yang tersimpan. Periksa cakupan dan waktu pengamatan sebelum membandingkan periode. Data yang hilang bukan berarti nol. Cuplikan akun terbaru memiliki waktu pengukuran sendiri dan belum tentu merupakan total periode. Insight Instagram untuk periode persis terpisah dari pengamatan terakumulasi. Pembacaan tidak memulai pengumpulan dari penyedia. posts refresh adalah tindakan terpisah untuk data postingan/komentar, bukan permintaan penyegaran analitik.

Daftar menggunakan kursor. --all mengikuti halaman; data dapat berubah selama penelusuran halaman, sehingga hasil bukan cuplikan satu titik waktu. Jika kursor kedaluwarsa, laporkan hasil yang tidak lengkap dan mulai daftar baru secara sengaja, alih-alih menggabungkannya diam-diam dengan halaman lama.

Siapkan berkas sebelum publikasi

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

Perintah pertama mendaftarkan dan mentransfer berkas. Simpan ID medianya meskipun transfer gagal atau respons tidak pasti. Perintah kedua meminta pemeriksaan; gunakan media hanya setelah status media akhir menjadi ready. Langkah ini tidak memublikasikan apa pun. Media dapat digunakan kembali dalam mereknya. Unggah secara terpisah untuk merek lain.

Jika hanya URL unggahan yang kedaluwarsa, gunakan media refresh-upload MEDIA_ID dengan lingkungan, sesi masuk, dan merek yang sama. URL baru tidak memperpanjang tenggat alur kerja asli atau mengganti berkas. Byte yang berbeda memerlukan unggahan media baru. Perlakukan URL transfer bertanda tangan sebagai kredensial dan jangan menyertakannya dalam transkrip bersama. Klien tanpa kemampuan transfer berkas dapat menggunakan URL kemajuan browser yang dikembalikan, masuk dan memilih berkas, lalu kembali dengan ID media yang sama untuk memeriksa kesiapan.

Tinjau dan publikasikan

Konfirmasikan merek, akun, teks lengkap, urutan segmen utas, lampiran, opsi penyedia, dan waktu eksekusi sebelum memublikasikan konten yang disiapkan AI. Persetujuan yang sudah ada untuk maksud yang persis sama sudah cukup. Permintaan analisis atau penyusunan draf saja bukan persetujuan publikasi.

Simpan input publikasi langsung minimal ini sebagai publish.json. Pilih akun yang mendukung kombinasi teks dan gambar yang diusulkan; server memeriksa ulang kemampuan saat ini, kesiapan media, dan izin.

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

Pilih dan simpan kunci unik untuk maksud ini sebelum mengirim. Gunakan kembali kunci dan payload yang persis sama setelah respons yang tidak pasti, termasuk saat berpindah antara API, CLI, dan MCP. Jangan membuat publikasi baru hanya karena koneksi habis waktu. Kunci yang sama dengan input yang berubah menimbulkan konflik. Kunci yang kedaluwarsa tidak membuat pekerjaan baru: periksa hasil lama sebelum sengaja memulai maksud baru.

Untuk penjadwalan, ganti scheduled_at: null dengan waktu UTC mendatang yang disetujui, misalnya 2026-12-01T09:00:00Z. Ganti tanggal ilustrasi ini sebelum digunakan dan pastikan masih berada di masa mendatang. Pendaftaran yang selesai mengembalikan publish_operation_id terpisah; ini tidak berarti postingan SNS terjadwal sudah dipublikasikan.

Pantau hasil

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

Untuk publikasi langsung, pantau ID operasi yang dikembalikan. Untuk publikasi terjadwal, pantau publish_operation_id pada waktu eksekusi. Menunggu bersifat opsional dan lokal. Kode keluar CLI 10 berarti batas tunggu habis; kode keluar 130 berarti penantian diinterupsi. Keduanya tidak membatalkan tugas server. Lanjutkan membaca operasi yang sama. Kode keluar 11 dari penantian menunjukkan hasil akhir gagal, dibatalkan, atau berhasil sebagian; periksa hasil per akun. Pencarian status biasa dapat keluar dengan 0 sambil melaporkan operasi gagal, sehingga skrip juga harus memeriksa status respons.

Laporkan setiap akun secara terpisah. Pertahankan postingan yang berhasil dan URL-nya. Array posts berurutan berisi postingan utas yang terkonfirmasi; post_url perwakilan saja mungkin tidak menggambarkan seluruh utas. URL yang tidak ada atau status yang belum terselesaikan bukan bukti bahwa penyedia tidak membuat apa pun. Biarkan hasil yang sedang direkonsiliasi dan yang tidak diketahui tetap belum terselesaikan sampai tugas yang ada memberikan bukti.

Ubah jadwal atau pulihkan kegagalan

Baca contents get CONTENT_ID dengan lingkungan, sesi masuk, dan merek yang sama sebelum mengubah konten atau waktu. Teruskan versi saat ini sebagai --expected-version. contents update mengedit target yang memenuhi syarat dan belum dimulai; contents reschedule mengubah jadwal UTC-nya. Konflik versi memerlukan pembacaan dan peninjauan baru, bukan penimpaan diam-diam. contents cancel meminta pembatalan; periksa operasi publikasi yang dikembalikan sampai pembatalan dikonfirmasi. Eksekusi mungkin lebih dahulu berlangsung.

Coba ulang hanya akun gagal terpilih yang saat ini ditandai 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

Ini adalah maksud eksekusi baru dan memerlukan kunci baru yang sesuai serta persetujuan pengguna, kecuali sudah tercakup. Simpan kunci percobaan ulang itu setelah respons yang tidak pasti. Percobaan ulang memakai konten tersimpan dan dijalankan sesegera mungkin; tindakan ini tidak pernah memublikasikan ulang target yang berhasil atau tidak pasti. Untuk jadwal baru di masa mendatang, contents duplicate hanya mengembalikan input yang dapat diedit. Tinjau lalu kirim publikasi baru yang disetujui.

Membuang entri antrean gagal yang memenuhi syarat menyembunyikannya dari antrean kerja; tindakan ini tidak menghapus postingan, menghapus riwayat eksekusi, atau mencoba ulang apa pun. Pembatalan massal dapat mengembalikan kelompok diterima dan ditolak sekaligus; pantau setiap operasi publikasi yang diterima. Pembuangan massal selesai secara sinkron: periksa kelompok yang dibuang dan ditolak pada tanda terima, tanpa menunggu operasi baru. Dalam kedua kasus, baca tanda terima lengkap alih-alih menganggap kode keluar sebagai hasil semuanya berhasil atau semuanya gagal.

Tangani kesalahan permintaan dan putuskan koneksi

Baca kode kesalahan terstruktur, ID permintaan, ID operasi bila tersedia, next_action, dan retry_at. Pemulihan autentikasi kembali ke operasi semula. Kesalahan izin memerlukan akses yang sah, bukan antarmuka lain. Batas laju dan pembatasan kemampuan harus dipatuhi. Permintaan yang dapat dicoba ulang tidak memberikan izin untuk publikasi baru atau kunci pengganti.

ankk auth logout --environment production --connection OAUTH_CONNECTION_ID

Keluar melaporkan pencabutan server secara terpisah dari penghapusan kredensial lokal. Jika pencabutan server belum dikonfirmasi, cabut koneksi lama dari pengaturan ANKK atau koneksi valid lainnya. Menghapus koneksi OAuth tidak membatalkan publikasi yang sudah diterima atau menghapus media milik merek.

Gunakan MCP dan Skills

MCP menggunakan OAuth pengguna di https://api.ankk.app/mcp/v2. Host memerlukan klien terdaftar; URL saja tidak menyelesaikan koneksi. Belum ada daftar resmi di direktori ChatGPT dan Claude. Jika kartu tidak tersedia, gunakan teks dan hasil terstruktur. Periksa nilai serta waktu pengamatan, bukan hanya ringkasan percakapan.

Skills menyediakan prosedur, bukan izin atau kredensial. Instal tag kandidat tetap berikut lalu periksa merek, persetujuan, dan hasil akhir.

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