OAuth v2 업무 흐름

설치

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

로그인하고 브랜드 선택하기

ANKK v2는 브라우저 OAuth로 사용자 계정을 인증한다. 모든 요청에 현재 사용자 권한이 적용되며 앱 연결이 브랜드 권한을 추가하지 않는다. 작업할 때 브랜드를 선택한다. OAuth 승인은 작업 브랜드 선택과 별개다.

Node.js 24 이상에서 CLI 0.5.1을 사용한다. 아래 public client ID는 ANKK CLI를 식별하며 비밀값이 아니다.

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

대문자로 표시한 식별자는 본인의 요청 결과에서 받은 ID로 바꾼다. OAuth 연결 ID는 로그인을 선택한다. SNS 계정 ID는 발행 대상을 나타내며 OAuth 연결 ID나 외부 서비스의 계정 ID와 다르다. 한 업무에서는 같은 환경과 브랜드를 사용한다. 예제는 로컬 기본 브랜드가 설정되어 있어도 환경과 브랜드를 명시한다.

브라우저가 자동으로 열리지 않는 터미널에서는 ankk auth login --environment production --device --no-open을 실행하고 표시되는 인증 안내를 따른다. 토큰은 OS 자격 증명 저장소에 보관한다. 저장소를 사용할 수 없으면 먼저 복구한다. 토큰을 대화창에 붙여 넣거나 발행 JSON 파일에 저장하지 않는다.

성과와 저장된 게시물 조회하기

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

실제 보고 기간을 지정한다. 시작 시각은 포함하고 종료 시각은 포함하지 않으며 UTC를 사용한다. 사용자가 지정한 현지 날짜를 UTC로 변환한 뒤 조회한다. 계정 하나로 범위를 좁히려면 --sns-account SNS_ACCOUNT_ID를 추가한다.

결과는 저장된 관측 데이터를 설명한다. 기간을 비교하기 전에 수집 범위와 관측 시각을 확인한다. 누락 데이터는 0이 아니다. 최신 계정 스냅샷은 별도의 측정 시각을 가지며 해당 기간의 합계라고 볼 수 없다. Instagram의 정확한 기간 인사이트는 누적 관측값과 구분한다. 조회가 외부 서비스 수집을 시작하지는 않는다. posts refresh는 게시물·댓글 데이터를 갱신하는 별도 작업이며 성과 갱신 요청이 아니다.

목록은 커서를 사용한다. --all은 다음 페이지를 따라가지만 조회 중 데이터가 바뀔 수 있으므로 동일 시점의 스냅샷은 아니다. 커서가 만료되면 결과가 불완전함을 알리고 새 목록 조회를 명시적으로 시작한다. 이전 페이지와 새 조회 결과를 조용히 합치지 않는다.

발행 전에 파일 준비하기

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

첫 명령은 파일을 등록하고 전송한다. 전송이 실패하거나 응답이 불확실해도 미디어 ID를 보관한다. 두 번째 명령은 검사를 요청하며 최종 미디어 상태가 ready일 때만 사용한다. 이 과정은 발행하지 않는다. 미디어는 같은 브랜드 안에서 재사용할 수 있고, 다른 브랜드에서는 별도로 업로드한다.

업로드 URL만 만료됐으면 같은 환경·로그인·브랜드로 media refresh-upload MEDIA_ID를 사용한다. 새 URL은 원래 업무 기한을 연장하거나 파일을 교체하지 않는다. 파일 바이트가 달라지면 새 미디어 업로드가 필요하다. 서명된 전송 URL은 자격 증명처럼 다루고 공유 대화에 남기지 않는다. 파일을 전송할 수 없는 클라이언트에서는 반환된 브라우저 진행 URL을 열어 로그인하고 파일을 선택한 뒤, 같은 미디어 ID로 준비 상태를 확인한다.

검토하고 발행하기

AI가 준비한 콘텐츠를 발행하기 전에 브랜드·계정·전체 본문·연속 게시 순서·첨부 파일·서비스별 옵션·실행 시각을 확인한다. 같은 내용과 대상·시점에 대한 기존 승인이 있으면 충분하다. 분석이나 초안 작성 요청만으로 발행이 승인되지는 않는다.

아래 최소 즉시 발행 입력을 publish.json으로 저장한다. 본문과 이미지 조합을 지원하는 계정을 선택한다. 서버는 현재 기능 지원·미디어 준비 상태·권한을 다시 검사한다. JSON 예제의 영어 본문은 승인된 실제 본문으로 바꾼다.

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

전송 전에 이번 발행 의도를 위한 고유 키를 정하고 보관한다. 응답이 불확실할 때는 API·CLI·MCP 사이를 옮기더라도 정확히 같은 키와 입력을 사용한다. 연결 시간이 초과됐다는 이유로 다른 발행을 만들지 않는다. 같은 키에 다른 입력을 보내면 충돌한다. 만료된 키는 새 작업을 만들지 않는다. 새 발행을 명시적으로 시작하기 전에 이전 결과부터 확인한다.

예약하려면 scheduled_at: null을 승인된 미래 UTC 시각으로 바꾼다. 예를 들어 2026-12-01T09:00:00Z를 사용할 수 있지만 실행 전에 실제 예약 시각으로 바꾸고 아직 미래인지 확인해야 한다. 등록 완료 결과는 별도의 publish_operation_id를 반환하며, SNS 게시물이 발행됐다는 뜻은 아니다.

최종 결과 확인하기

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

즉시 발행은 반환된 작업 ID를 조회한다. 예약은 실행 시점에 publish_operation_id를 조회한다. 대기는 선택 사항이며 로컬에서 수행된다. CLI 종료 코드 10은 대기 제한 초과, 130은 대기 중단을 뜻한다. 어느 경우도 서버 작업을 취소하지 않는다. 같은 작업을 계속 조회한다. 대기 명령의 종료 코드 11은 실패·취소·부분 성공으로 끝났음을 뜻하므로 계정별 결과를 확인한다. 일반 상태 조회는 실패한 작업을 반환하면서도 종료 코드 0으로 끝날 수 있으므로 스크립트는 응답 상태도 검사해야 한다.

계정별 결과를 따로 보고한다. 성공한 게시물과 URL을 보존한다. 순서가 있는 posts 배열은 연속 게시의 확인된 게시물을 담는다. 대표 post_url 하나가 전체 연속 게시를 설명하지 않을 수 있다. URL이 없거나 상태가 미확정이라고 해서 외부 서비스에 아무것도 생성되지 않았다고 단정하지 않는다. 기존 작업에서 근거를 얻을 때까지 reconciling과 불명확한 결과는 미확정으로 유지한다.

예약 변경과 실패 복구

내용이나 시각을 바꾸기 전에 같은 환경·로그인·브랜드로 contents get CONTENT_ID를 조회한다. 현재 버전을 --expected-version으로 전달한다. contents update는 시작 전이며 변경 가능한 대상의 내용을 수정하고, contents reschedule은 그 대상의 UTC 예약 시각을 바꾼다. 버전 충돌이 발생하면 다시 조회하고 검토한다. 조용히 덮어쓰지 않는다. contents cancel은 취소를 요청한다. 반환된 발행 작업을 조회해 취소 확정 여부를 확인한다. 경합에서 실행이 먼저 완료될 수도 있다.

현재 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

재시도는 새로운 실행 의도이므로 그에 맞는 새 키를 사용하며 기존 승인에 포함되지 않았다면 사용자 승인이 필요하다. 응답이 불확실해도 재시도 키를 유지한다. 재시도는 저장된 콘텐츠로 가능한 즉시 실행하며 성공했거나 결과가 불명확한 대상은 다시 발행하지 않는다. 새로운 미래 예약이 필요하면 contents duplicate로 편집용 입력만 받아 검토한 뒤 새로 승인된 발행을 요청한다.

정리 가능한 실패 항목을 discard하면 작업 대기열에서 숨겨진다. 게시물 삭제·실행 이력 삭제·재시도를 뜻하지 않는다. 일괄 취소는 접수·거절 그룹이 함께 반환될 수 있으며 접수된 발행 작업을 각각 조회한다. 일괄 discard는 동기적으로 완료되므로 새 작업을 기다리지 않고 응답의 정리·거절 그룹을 검사한다. 두 경우 모두 종료 코드를 전체 성공/실패로 해석하지 말고 전체 응답을 읽는다.

요청 오류 처리와 연결 해제

구조화된 오류 코드·요청 ID·제공되는 작업 ID·next_action·retry_at을 확인한다. 인증을 복구한 뒤에는 원래 작업으로 돌아간다. 권한 오류에는 정당한 접근 권한이 필요하며 다른 인터페이스로 우회하지 않는다. 요청량 제한과 기능 제한을 지킨다. 요청을 재시도할 수 있다는 안내가 새 발행이나 키 교체를 승인하는 것은 아니다.

ankk auth logout --environment production --connection OAUTH_CONNECTION_ID

로그아웃은 서버 연결 해제와 로컬 자격 증명 제거를 구분해 보고한다. 서버 해제가 확인되지 않으면 ANKK 설정이나 다른 유효한 연결에서 이전 연결을 해제한다. OAuth 연결을 제거해도 이미 접수된 발행이 취소되거나 브랜드 소유 미디어가 삭제되지는 않는다.

MCP와 Skills 사용하기

MCP는 https://api.ankk.app/mcp/v2에서 사용자 OAuth를 사용한다. 호스트에 등록된 client가 필요하며 URL 입력만으로 연결이 완료되지는 않는다. ChatGPT·Claude 공식 디렉터리 등록은 제공하지 않는다. 카드가 없으면 텍스트·구조화 결과를 사용하고, 대화 요약만 믿지 말고 성과 값과 관측 시각을 확인한다.

Skills는 업무 절차이며 권한이나 자격 증명을 제공하지 않는다. 아래 고정 후보 태그를 설치하고 브랜드·사용자 승인·작업 최종 결과를 확인한다.

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