[!WARNING] 이 프로젝트는 다방 공식 제품이나 공식 SDK가 아닙니다. 내부 응답 구조나 HTTP 계약이 바뀌면 동작이 깨질 수 있습니다.

Overview

dabangcli는 상위 자동화나 AI가 만든 canonical request를 받아 다방 검색 실행으로 연결하는 adapter입니다.

• 입력은 canonical JSON request
• 출력은 single JSON envelope
• 목록 검색은 direct HTTP
• 상세 조회는 direct HTTP
• open만 사용자 브라우저를 엽니다

실행 흐름은 단순합니다.

request-schema / filters
        ->
preview
        ->
run
        ->
detail / open

Quick Start

Install from npm

일반 사용은 npm 배포본 설치를 기준으로 합니다.

npm i -g dabangcli

dabangcli -h

What It Does

| Need | dabangcli | | ---------------------------------------- | ------------------------------------------------- | | 검색 조건을 provider query로 바꾸고 싶다 | canonical request를 다방 route/query로 매핑합니다 | | 실제 목록을 JSON으로 받고 싶다 | run이 목록 검색을 실행합니다 | | 상세를 후속 자동화에 넘기고 싶다 | detail이 normalized detail JSON을 반환합니다 | | 사람이 직접 provider 페이지를 보고 싶다 | open이 상세 페이지를 엽니다 |

What It Does Not Do

• 자연어를 해석해 검색 조건을 알아서 만드는 일
• 통근 시간, 역세권, 생활권 같은 planner 역할
• 다방 공식 API를 제공하는 일
• 장기 호환성을 보장하는 일

Commands

| Command | Purpose | | -------------------------- | ---------------------------------------------------------------------- | | request-schema | CLI가 받는 canonical request schema를 반환합니다 | | filters | raw provider filter catalog를 반환합니다 | | preview [request] | canonical request가 실제 다방 route/query로 어떻게 바뀌는지 보여줍니다 | | run [request] | 목록 검색을 실행합니다 | | detail --id <listing-id> | listing id 기준 normalized detail JSON을 반환합니다 | | open --id <listing-id> | listing id 기준 provider 상세 페이지를 엽니다 |

Command Examples

dabangcli preview ./request.json
dabangcli run ./request.json
dabangcli detail --id dabang:onetwo:697487c5edbdd457a982682d
dabangcli open --id dabang:apt:693a1f98abc8fe13c5fb3af5

Stdin Mode

cat request.json | dabangcli run --stdin

Request Shape

아래는 강남역 근처 원룸 전세 검색 예시입니다.

{
    "providerSearch": {
        "provider": "dabang",
        "category": "onetwo",
        "map": {
            "lat": 37.494367328004216,
            "lng": 127.01446798508894,
            "zoom": 11
        },
        "commonFilters": {
            "sellingTypes": ["lease"],
            "deposit": {"min": null, "max": 30000},
            "rent": null,
            "trade": null,
            "includeMaintenance": false,
            "shortLeaseOnly": false,
            "pyeong": {"min": 8, "max": null},
            "useApprovalDate": null
        },
        "categoryFilters": {
            "roomTypes": ["oneRoom"]
        }
    }
}

입력 스키마와 enum 목록은 아래 명령으로 바로 확인할 수 있습니다.

dabangcli request-schema

Output Shape

모든 명령은 stdout에 single JSON envelope만 출력합니다.

run 성공 응답에는 data.meta.source = "http"가 들어갑니다.

Success Example

{
    "ok": true,
    "command": "run",
    "data": {
        "items": [],
        "meta": {
            "count": 0,
            "source": "http",
            "requestUrl": "https://www.dabangapp.com/api/...",
            "pageUrl": "https://www.dabangapp.com/map/...",
            "status": 200
        }
    },
    "meta": {}
}

Failure Example

{
    "ok": false,
    "command": "run",
    "error": {
        "code": "PROVIDER_UNAVAILABLE",
        "message": "다방 provider 요청이 실패했습니다.",
        "hint": "잠시 후 다시 시도하거나 provider 상태를 확인하세요. 문제가 계속되면 이슈로 제보해주세요: https://github.com/SeoJaeWan/dabangcli/issues/new"
    }
}

Supported Scope

현재 문서화 및 구현 기준으로 다루는 카테고리:

• onetwo
• apt
• house
• officetel
• saleInLots

현재 중요한 동작:

• run은 direct HTTP list 경로만 사용합니다
• detail은 residential detail HTTP 경로를 직접 사용합니다
• fixture는 내부 테스트/회귀 고정용이며 공개 CLI 옵션으로 노출하지 않습니다

최근 로컬 검증 기준:

• run 실제 응답에서 meta.source: "http" 확인
• 동일 요청을 src/cli.ts와 dist/cli.js 양쪽에서 확인

Operational Notes

If run Fails

• direct HTTP list 헤더나 내부 파라미터 계약이 바뀌면 run이 바로 실패할 수 있습니다
• provider 연결 실패나 payload 파싱 실패 시에는 이슈 등록 URL이 hint에 함께 포함됩니다
• issue URL: https://github.com/SeoJaeWan/dabangcli/issues/new

Known Risks

• 다방 웹 구조나 내부 응답이 바뀌면 run 경로가 깨질 수 있습니다
• preview는 의도된 query preview이고, run은 실제 live provider 실행 결과입니다
• 결과 0건은 실패가 아니라 정상 실행 + 검색 결과 없음일 수 있습니다

FAQ

공식 API인가요?
아닙니다. 비공식 CLI입니다.

왜 preview와 run을 나눴나요?
실행 전에 요청이 어떻게 변환되는지 확인할 수 있게 하기 위해서입니다.

왜 detail과 open을 나눴나요?
detail은 JSON 반환이고, open은 side effect이기 때문입니다.

0건이면 실패인가요?
아닙니다. ok: true, count: 0이면 정상 실행 + 검색 결과 없음입니다.