@kiyeonjeon21/ncli 0.1.1

package/dist/schemas/index.js

@@ -0,0 +1,323 @@
+export const SCHEMAS = {
+    search: {
+        description: "Naver Search APIs",
+        methods: {
+            "search.blog": {
+                httpMethod: "GET",
+                path: "/v1/search/blog.json",
+                description: "Search Naver blogs",
+                rateLimit: "25,000/day",
+                parameters: {
+                    query: { type: "string", required: true, description: "Search query" },
+                    display: { type: "integer", default: 10, min: 1, max: 100, description: "Number of results" },
+                    start: { type: "integer", default: 1, min: 1, max: 1000, description: "Start position" },
+                    sort: { type: "string", enum: ["sim", "date"], default: "sim", description: "Sort order" },
+                },
+                response: {
+                    fields: ["lastBuildDate", "total", "start", "display", "items"],
+                    itemFields: ["title", "link", "description", "bloggername", "bloggerlink", "postdate"],
+                },
+            },
+            "search.news": {
+                httpMethod: "GET",
+                path: "/v1/search/news.json",
+                description: "Search Naver news",
+                rateLimit: "25,000/day",
+                parameters: {
+                    query: { type: "string", required: true, description: "Search query" },
+                    display: { type: "integer", default: 10, min: 1, max: 100 },
+                    start: { type: "integer", default: 1, min: 1, max: 1000 },
+                    sort: { type: "string", enum: ["sim", "date"], default: "sim" },
+                },
+                response: {
+                    itemFields: ["title", "originallink", "link", "description", "pubDate"],
+                },
+            },
+            "search.web": {
+                httpMethod: "GET",
+                path: "/v1/search/web.json",
+                description: "Search web pages",
+                rateLimit: "25,000/day",
+                parameters: {
+                    query: { type: "string", required: true },
+                    display: { type: "integer", default: 10, min: 1, max: 100 },
+                    start: { type: "integer", default: 1, min: 1, max: 1000 },
+                },
+                response: {
+                    itemFields: ["title", "link", "description"],
+                },
+            },
+            "search.image": {
+                httpMethod: "GET",
+                path: "/v1/search/image",
+                description: "Search images",
+                rateLimit: "25,000/day",
+                parameters: {
+                    query: { type: "string", required: true },
+                    display: { type: "integer", default: 10, min: 1, max: 100 },
+                    start: { type: "integer", default: 1, min: 1, max: 1000 },
+                    sort: { type: "string", enum: ["sim", "date"], default: "sim" },
+                    filter: { type: "string", enum: ["all", "large", "medium", "small"], default: "all" },
+                },
+                response: {
+                    itemFields: ["title", "link", "thumbnail", "sizeheight", "sizewidth"],
+                },
+            },
+            "search.book": {
+                httpMethod: "GET",
+                path: "/v1/search/book.json",
+                description: "Search books",
+                rateLimit: "25,000/day",
+                parameters: {
+                    query: { type: "string", required: true },
+                    display: { type: "integer", default: 10, min: 1, max: 100 },
+                    start: { type: "integer", default: 1, min: 1, max: 1000 },
+                    sort: { type: "string", enum: ["sim", "date"], default: "sim" },
+                },
+                response: {
+                    itemFields: ["title", "link", "image", "author", "discount", "publisher", "pubdate", "isbn", "description"],
+                },
+            },
+            "search.cafe": {
+                httpMethod: "GET",
+                path: "/v1/search/cafearticle.json",
+                description: "Search Naver cafe articles",
+                rateLimit: "25,000/day",
+                parameters: {
+                    query: { type: "string", required: true },
+                    display: { type: "integer", default: 10, min: 1, max: 100 },
+                    start: { type: "integer", default: 1, min: 1, max: 1000 },
+                    sort: { type: "string", enum: ["sim", "date"], default: "sim" },
+                },
+                response: {
+                    itemFields: ["title", "link", "description", "cafename", "cafeurl"],
+                },
+            },
+            "search.kin": {
+                httpMethod: "GET",
+                path: "/v1/search/kin.json",
+                description: "Search Naver Knowledge iN (Q&A)",
+                rateLimit: "25,000/day",
+                parameters: {
+                    query: { type: "string", required: true },
+                    display: { type: "integer", default: 10, min: 1, max: 100 },
+                    start: { type: "integer", default: 1, min: 1, max: 1000 },
+                    sort: { type: "string", enum: ["sim", "date", "count", "point"], default: "sim" },
+                },
+                response: {
+                    itemFields: ["title", "link", "description"],
+                },
+            },
+            "search.encyclopedia": {
+                httpMethod: "GET",
+                path: "/v1/search/encyc.json",
+                description: "Search encyclopedia",
+                rateLimit: "25,000/day",
+                parameters: {
+                    query: { type: "string", required: true },
+                    display: { type: "integer", default: 10, min: 1, max: 100 },
+                    start: { type: "integer", default: 1, min: 1, max: 1000 },
+                },
+                response: {
+                    itemFields: ["title", "link", "description", "thumbnail"],
+                },
+            },
+            "search.shop": {
+                httpMethod: "GET",
+                path: "/v1/search/shop.json",
+                description: "Search shopping items",
+                rateLimit: "25,000/day",
+                parameters: {
+                    query: { type: "string", required: true },
+                    display: { type: "integer", default: 10, min: 1, max: 100 },
+                    start: { type: "integer", default: 1, min: 1, max: 1000 },
+                    sort: { type: "string", enum: ["sim", "date", "asc", "dsc"], default: "sim" },
+                },
+                response: {
+                    itemFields: ["title", "link", "image", "lprice", "hprice", "mallName", "productId", "productType", "brand", "maker", "category1", "category2", "category3", "category4"],
+                },
+            },
+            "search.local": {
+                httpMethod: "GET",
+                path: "/v1/search/local.json",
+                description: "Search local places (restaurants, shops, etc.)",
+                rateLimit: "25,000/day",
+                parameters: {
+                    query: { type: "string", required: true, description: "Search query" },
+                    display: { type: "integer", default: 1, min: 1, max: 5, description: "Number of results" },
+                    start: { type: "integer", default: 1, min: 1, max: 1, description: "Start position" },
+                    sort: { type: "string", enum: ["random", "comment"], default: "random", description: "Sort order" },
+                },
+                response: {
+                    itemFields: ["title", "link", "category", "description", "telephone", "address", "roadAddress", "mapx", "mapy"],
+                },
+            },
+            "search.errata": {
+                httpMethod: "GET",
+                path: "/v1/search/errata.json",
+                description: "Spell check / typo correction",
+                rateLimit: "25,000/day",
+                parameters: {
+                    query: { type: "string", required: true, description: "Text to check for typos" },
+                },
+                response: {
+                    fields: ["errata"],
+                    note: "Returns corrected text or empty string if no error",
+                },
+            },
+            "search.adult": {
+                httpMethod: "GET",
+                path: "/v1/search/adult.json",
+                description: "Adult content keyword detection",
+                rateLimit: "25,000/day",
+                parameters: {
+                    query: { type: "string", required: true, description: "Keyword to check" },
+                },
+                response: {
+                    fields: ["adult"],
+                    note: "Returns 0 (general) or 1 (adult content)",
+                },
+            },
+            "search.doc": {
+                httpMethod: "GET",
+                path: "/v1/search/doc.json",
+                description: "Search professional/scholarly documents",
+                rateLimit: "25,000/day",
+                parameters: {
+                    query: { type: "string", required: true, description: "Search query" },
+                    display: { type: "integer", default: 10, min: 1, max: 100, description: "Number of results" },
+                    start: { type: "integer", default: 1, min: 1, max: 1000, description: "Start position" },
+                },
+                response: {
+                    itemFields: ["title", "link", "description"],
+                },
+            },
+        },
+    },
+    captcha: {
+        description: "Naver CAPTCHA APIs (image and voice)",
+        methods: {
+            "captcha.imageKey": {
+                httpMethod: "GET",
+                path: "/v1/captcha/nkey",
+                description: "Issue or verify image CAPTCHA key",
+                rateLimit: "1,000/day",
+                parameters: {
+                    code: { type: "integer", required: true, enum: [0, 1], description: "0: issue key, 1: verify input" },
+                    key: { type: "string", required: false, description: "CAPTCHA key (required when code=1)" },
+                    value: { type: "string", required: false, description: "User input to verify (required when code=1)" },
+                },
+                response: {
+                    fields: ["key", "result", "error"],
+                },
+            },
+            "captcha.imageFile": {
+                httpMethod: "GET",
+                path: "/v1/captcha/ncaptcha.bin",
+                description: "Download CAPTCHA image (JPG)",
+                rateLimit: "1,000/day",
+                parameters: {
+                    key: { type: "string", required: true, description: "CAPTCHA key from nkey API" },
+                },
+                response: {
+                    note: "Returns JPG image binary",
+                },
+            },
+            "captcha.voiceKey": {
+                httpMethod: "GET",
+                path: "/v1/captcha/skey",
+                description: "Issue or verify voice CAPTCHA key",
+                rateLimit: "1,000/day",
+                parameters: {
+                    code: { type: "integer", required: true, enum: [0, 1], description: "0: issue key, 1: verify input" },
+                    key: { type: "string", required: false, description: "CAPTCHA key (required when code=1)" },
+                    value: { type: "string", required: false, description: "User input to verify (required when code=1)" },
+                },
+                response: {
+                    fields: ["key", "result", "error"],
+                },
+            },
+            "captcha.voiceFile": {
+                httpMethod: "GET",
+                path: "/v1/captcha/scaptcha",
+                description: "Download CAPTCHA voice audio (WAV)",
+                rateLimit: "1,000/day",
+                parameters: {
+                    key: { type: "string", required: true, description: "CAPTCHA key from skey API" },
+                },
+                response: {
+                    note: "Returns WAV audio binary",
+                },
+            },
+        },
+    },
+    datalab: {
+        description: "Naver DataLab APIs",
+        methods: {
+            "datalab.trend": {
+                httpMethod: "POST",
+                path: "/v1/datalab/search",
+                description: "Search keyword trend analysis",
+                rateLimit: "1,000/day",
+                request: {
+                    startDate: { type: "string", required: true, format: "yyyy-mm-dd", description: "Start date" },
+                    endDate: { type: "string", required: true, format: "yyyy-mm-dd", description: "End date" },
+                    timeUnit: { type: "string", required: true, enum: ["date", "week", "month"], description: "Time unit" },
+                    keywordGroups: {
+                        type: "array",
+                        required: true,
+                        description: "Keyword groups (max 5)",
+                        items: {
+                            groupName: { type: "string", required: true },
+                            keywords: { type: "array", items: "string", required: true },
+                        },
+                    },
+                    device: { type: "string", enum: ["", "pc", "mo"], description: "Device filter" },
+                    gender: { type: "string", enum: ["", "m", "f"], description: "Gender filter" },
+                    ages: { type: "array", items: "string", description: "Age groups" },
+                },
+            },
+            "datalab.shopping": {
+                httpMethod: "POST",
+                path: "/v1/datalab/shopping/categories",
+                description: "Shopping insight by category",
+                rateLimit: "1,000/day",
+                request: {
+                    startDate: { type: "string", required: true, format: "yyyy-mm-dd" },
+                    endDate: { type: "string", required: true, format: "yyyy-mm-dd" },
+                    timeUnit: { type: "string", required: true, enum: ["date", "week", "month"] },
+                    category: { type: "array", required: true, description: "Category codes" },
+                    device: { type: "string", enum: ["", "pc", "mo"] },
+                    gender: { type: "string", enum: ["", "m", "f"] },
+                    ages: { type: "array", items: "string" },
+                },
+            },
+        },
+    },
+};
+export function listServices() {
+    return {
+        services: Object.entries(SCHEMAS).map(([name, schema]) => ({
+            name,
+            description: schema.description,
+        })),
+    };
+}
+export function listMethods(service) {
+    const svc = SCHEMAS[service];
+    if (!svc)
+        return null;
+    const methods = svc.methods;
+    return {
+        service,
+        methods: Object.keys(methods),
+    };
+}
+export function getSchema(method) {
+    const [service] = method.split(".");
+    const svc = SCHEMAS[service];
+    if (!svc)
+        return null;
+    const methods = svc.methods;
+    return methods[method] ?? null;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@kiyeonjeon21/ncli",
+  "version": "0.1.1",
+  "description": "Agent-native CLI for Naver Open APIs",
+  "type": "module",
+  "bin": {
+    "ncli": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "CONTEXT.md",
+    "AGENTS.md",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "preversion": "npm test && npm run build",
+    "postversion": "git push && git push --tags",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kiyeonjeon21/naver-cli.git"
+  },
+  "keywords": [
+    "naver",
+    "cli",
+    "agentic",
+    "ai-agent",
+    "openapi"
+  ],
+  "author": "Kiyeon Jeon",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^14.0.3",
+    "dotenv": "^17.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  }
+}

package/skills/datalab.md

@@ -0,0 +1,80 @@
+---
+name: naver-datalab
+description: Rules and patterns for using naver CLI DataLab APIs. Use when analyzing search trends or shopping insights.
+---
+
+# naver datalab Operations
+
+## Rules
+
+1. Always use `--json` with full payload — DataLab APIs require structured input
+2. Always use `--output json` for output
+3. Rate limit is 1,000 calls/day — use sparingly
+4. Date format is `yyyy-mm-dd`
+5. `timeUnit` must be one of: `date`, `week`, `month`
+6. Maximum 5 keyword groups per request
+
+## Authentication
+
+```bash
+export NAVER_CLIENT_ID="your-client-id"
+export NAVER_CLIENT_SECRET="your-client-secret"
+```
+
+## Workflows
+
+### Search keyword trend
+
+```bash
+naver datalab trend --json '{
+  "startDate": "2026-01-01",
+  "endDate": "2026-04-01",
+  "timeUnit": "month",
+  "keywordGroups": [
+    {"groupName": "AI", "keywords": ["인공지능", "AI"]},
+    {"groupName": "블록체인", "keywords": ["블록체인", "blockchain"]}
+  ]
+}'
+```
+
+### Shopping category trend
+
+```bash
+naver datalab shopping --json '{
+  "startDate": "2026-01-01",
+  "endDate": "2026-04-01",
+  "timeUnit": "month",
+  "category": [
+    {"name": "노트북", "param": ["50000832"]}
+  ]
+}'
+```
+
+### With filters
+
+```bash
+naver datalab trend --json '{
+  "startDate": "2026-01-01",
+  "endDate": "2026-04-01",
+  "timeUnit": "week",
+  "keywordGroups": [{"groupName": "test", "keywords": ["테스트"]}],
+  "device": "mo",
+  "gender": "f",
+  "ages": ["20", "30"]
+}'
+```
+
+## Schema Introspection
+
+```bash
+naver schema datalab.trend
+naver schema datalab.shopping
+```
+
+## Error Handling
+
+| Error Code | Meaning | Action |
+|------------|---------|--------|
+| `AUTH_REQUIRED` | Missing credentials | Set environment variables |
+| `HTTP_400` | Bad request | Check required fields: startDate, endDate, timeUnit, keywordGroups/category |
+| `HTTP_429` | Rate limited (1,000/day) | This is a hard daily limit — plan queries carefully |

package/skills/search.md

@@ -0,0 +1,66 @@
+---
+name: naver-search
+description: Rules and patterns for using naver CLI to search Naver services. Use when searching blog, news, web, image, book, cafe, kin, encyclopedia, or shop.
+---
+
+# naver search Operations
+
+## Rules
+
+1. Always use `--output json` for all commands
+2. Always add `--fields` to minimize response size
+3. Preferred fields for common searches:
+   - blog: `title,link,description,bloggername,postdate`
+   - news: `title,link,description,pubDate`
+   - shop: `title,link,lprice,mallName,brand`
+   - book: `title,author,publisher,isbn,description`
+4. Use `--json` for complex queries with multiple parameters
+5. Use `--sanitize` when response data will be injected into agent context
+
+## Authentication
+
+```bash
+export NAVER_CLIENT_ID="your-client-id"
+export NAVER_CLIENT_SECRET="your-client-secret"
+```
+
+## Workflows
+
+### Quick search
+
+```bash
+naver search blog "검색어" --fields "title,link,description"
+```
+
+### Paginated search
+
+```bash
+# Page 1
+naver search news "AI" --display 10 --start 1 --fields "title,link,pubDate"
+
+# Page 2
+naver search news "AI" --display 10 --start 11 --fields "title,link,pubDate"
+```
+
+### JSON payload
+
+```bash
+naver search shop --json '{"query":"맥북","display":5,"sort":"dsc"}' \
+  --fields "title,lprice,hprice,mallName"
+```
+
+## Schema Introspection
+
+```bash
+naver schema search.blog
+naver schema search.shop
+```
+
+## Error Handling
+
+| Error Code | Meaning | Action |
+|------------|---------|--------|
+| `AUTH_REQUIRED` | Missing credentials | Set environment variables |
+| `HTTP_400` | Bad request | Check schema for valid parameters |
+| `HTTP_429` | Rate limited (25,000/day) | Wait and retry |
+| `MISSING_QUERY` | No query provided | Add query argument |