heyyumi 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +100 -18
  2. package/package.json +13 -4
  3. package/src/commands.js +22 -7
package/README.md CHANGED
@@ -1,18 +1,93 @@
1
1
  # heyyumi
2
2
 
3
- Your AI finds and books real Korean restaurants, no Korean needed.
3
+ [![npm](https://img.shields.io/npm/v/heyyumi)](https://www.npmjs.com/package/heyyumi)
4
+ [![node](https://img.shields.io/node/v/heyyumi)](https://www.npmjs.com/package/heyyumi)
5
+ [![license](https://img.shields.io/npm/l/heyyumi)](https://github.com/hmp-dev/heyyumi-cli/blob/main/LICENSE)
4
6
 
5
- `heyyumi` is the command-line client for [HeyYumi](https://heyyumi.ai): verified data on 540,000+ restaurants, cafes, bakeries and bars across Korea, plus table requests that the venue answers within 5 minutes. It is built for AI agents (Claude Code, Codex, Cursor, k-skill …) that run shell commands and read JSON.
7
+ **Your AI finds and books real Korean restaurants, no Korean needed.**
8
+
9
+ Ask your agent for *"bibimbap near Myeongdong"*, *"a place BTS's Jin goes to for naengmyeon"* or *"somewhere open for dinner in Hongdae where nobody minds that I don't speak Korean"*. HeyYumi answers from verified data on **546,000+ restaurants, cafes and bars across Korea**, and sends the table request to the restaurant itself. Within 5 minutes you know whether the table is yours.
10
+
11
+ ```bash
12
+ npx -y heyyumi login # once: Google sign-in in the browser, a key is made for you
13
+ npx -y heyyumi search bibimbap --region Myeongdong
14
+ npx -y heyyumi reserve <placeId> --time "2026-10-25 19:00" --party 2 --phone +1-415-555-0100 --email you@example.com
15
+ ```
16
+
17
+ Works with any agent that runs shell commands and reads JSON: Claude Code, Codex, Gemini CLI, Cursor, or your own scripts. Node.js 18+, zero dependencies, free for personal use.
18
+
19
+ ## What your agent gets
20
+
21
+ **Real data, cross-checked.** 371,000+ restaurants, 138,000+ cafes and 37,000+ bars. More than 432,000 of them are confirmed by more than one independent source, and every record carries a confidence score and a last-seen date. Menus, prices, opening hours, last orders and break times are included wherever they are known. Nothing is invented: there are no star ratings, and a missing field means "unknown", never "no".
22
+
23
+ **Ask in your own language.** Dish names in English, romanized Korean, Japanese or Chinese are mapped to the Korean dish through an official government list of 800 Korean dishes and their foreign names. `bibimbap`, `ビビンバ` and `拌饭` all become 비빔밥. Places can be typed the same way: `Hongdae`, `Gangnam Station`, `Jeju Airport`.
24
+
25
+ **Book from the conversation.** `reserve` sends a real request to the restaurant, and `wait` returns `confirmed`, `cancelled` (with the venue's reason, if it gave one) or `expired`. The venue has 5 minutes to answer. Foreign phone numbers are welcome with an email address. Many venues can take a request, and the JSON says which ones (`yumiBooking.canRequest`).
26
+
27
+ **Ask the owner right now.** At Yumi partner venues, `live` asks the owner directly: is the dish still available, how long is the wait, are there seats for 10 right now? The question goes to the owner's phone, and they have 5 minutes to reply.
28
+
29
+ **Search the way travelers actually ask.** Over 60 filters, including:
30
+
31
+ | Ask for | Flag |
32
+ |---|---|
33
+ | Places where you don't need Korean (English menu or staff who speak your language) | `--foreigner-friendly` · `--english-menu` · `--foreign-languages ja` |
34
+ | Places a K-pop star or K-drama is known for (with the news source) | `--associated-with BTS` · `--associated-with 도깨비` |
35
+ | Shops on official long-running lists (30+ years) | `--legacy` |
36
+ | Vegan meals for a mixed group, vegetarian, gluten-free | `--dietary mixed_group_suitable` · `--dietary gluten_free` |
37
+ | Known to welcome Muslim guests (not a halal certification) | `--muslim-friendly` |
38
+ | Open at a time or a meal, last orders included | `--open-at "2026-10-25 19:00"` · `--open-at dinner` |
39
+ | Hanok, rooftop, ocean or river view, temple food, a city's signature food | `--hanok` · `--rooftop` · `--view ocean` · `--temple-food` · `--local-food Busan` |
40
+ | Alipay, WeChat Pay, Apple Pay, UnionPay | `--payment-methods alipay` |
41
+
42
+ Coverage today: Seoul, Gyeonggi, Busan, Jeju, Incheon, Daejeon, Sejong, Chungbuk and Chungnam, and growing.
43
+
44
+ ## What it looks like
6
45
 
7
46
  ```bash
8
- npx -y heyyumi login # once: Google sign-in in the browser, then done
9
- npx -y heyyumi search 냉면 --region 을지로 --page-size 5
10
- npx -y heyyumi place 2069798395
11
- npx -y heyyumi reserve 2069798395 --time "2026-10-25 19:00" --party 2 --phone 010-1234-5678 --name "Kim"
12
- npx -y heyyumi wait sbx_r_... # confirmed / cancelled / expired
47
+ $ npx -y heyyumi search bibimbap --region Myeongdong --page-size 3 --fields core
13
48
  ```
14
49
 
15
- Requires Node.js 18+. No other dependencies.
50
+ ```jsonc
51
+ {
52
+ "resolvedAs": "명동 상권",
53
+ "data": [
54
+ {
55
+ "id": "8392850",
56
+ "name": "본죽&비빔밥 명동점",
57
+ "address": { "road": "서울특별시 중구 명동8가길 6 2층" },
58
+ "confidence": 0.87,
59
+ "distanceM": 241,
60
+ "placeUrl": "https://heyyumi.ai/en/places/8392850",
61
+ "matchReason": "name",
62
+ "yumiBooking": { "canRequest": true, "requestHours": "10:00-20:00 KST" }
63
+ },
64
+ {
65
+ "name": "방이옥 종로점",
66
+ "matchReason": "representative_menu",
67
+ "matchedMenu": ["[점심특선] 한우육회 비빔밥 (1인)"]
68
+ // ...
69
+ }
70
+ ],
71
+ "meta": {
72
+ "total": 308,
73
+ "sort": "discovery",
74
+ "keywordTranslated": { "from": "bibimbap", "to": "비빔밥", "source": "official_dish_name" }
75
+ }
76
+ }
77
+ ```
78
+
79
+ Names and addresses come back in Korean, which is what taxi drivers and map apps expect. Your agent reads the JSON and answers in whatever language the user wrote in. `matchReason` tells it whether a place is a specialist or just also sells the dish.
80
+
81
+ ## Try these
82
+
83
+ ```bash
84
+ npx -y heyyumi search --region Seoul --associated-with BTS --page-size 5
85
+ npx -y heyyumi search 고기국수 --region "Jeju Airport" --open-at lunch
86
+ npx -y heyyumi search --region Gangnam --subtype korean_bbq --bbq-meat pork --private-room
87
+ npx -y heyyumi search --region Seongsu --dietary mixed_group_suitable --open-at dinner
88
+ npx -y heyyumi search --region Busan --local-food Busan --exclude 돼지국밥
89
+ npx -y heyyumi place <placeId> --fields all # menu, hours, attributes, reputation
90
+ ```
16
91
 
17
92
  ## Sign in once
18
93
 
@@ -21,14 +96,14 @@ Requires Node.js 18+. No other dependencies.
21
96
  - Each sign-in gets its own HeyYumi key on the user's account, so usage is metered per user.
22
97
  - Credentials are saved to `~/.config/heyyumi/credentials.json` (mode 0600; `%APPDATA%\heyyumi` on Windows). Access tokens refresh on their own; refresh is locked across processes so parallel agent commands never sign the user out.
23
98
  - `heyyumi status` shows whether you are signed in (never prints tokens). `heyyumi logout` removes local credentials. Keys can be revoked any time at <https://heyyumi.ai/dashboard>.
24
- - `--no-browser` prints the URL instead of opening it. `--client-name NAME` labels the connection (it shows up as the source of reservation requests, e.g. `--client-name k-skill`).
99
+ - `--no-browser` prints the URL instead of opening it. `--client-name NAME` labels the connection (it shows up as the source of reservation requests, e.g. `--client-name "My Agent"`).
25
100
  - Already have a dashboard key? Set `HEYYUMI_API_KEY=hmp_...` and skip `login`.
26
101
 
27
102
  ## Commands
28
103
 
29
104
  | Command | What it does |
30
105
  |---|---|
31
- | `search [KEYWORD] --region NAME [filters]` | Shortlist venues. `--region` takes Korean or romanized names, stations and landmarks (`Hongdae`, `강남역`, `제주공항`). Every `search_places` filter works as a flag: `--subtype korean_bbq`, `--open_at dinner`, `--parking`, `--reservation_channel yumi`, `--dietary vegan_options` … (see `heyyumi tools search_places`). Returns 10 venues unless `--page-size` is given. |
106
+ | `search [KEYWORD] --region NAME [filters]` | Shortlist venues. `--region` takes Korean or romanized names, stations and landmarks (`Hongdae`, `강남역`, `제주공항`). Every `search_places` filter works as a flag (see `heyyumi tools search_places`). Returns 10 venues unless `--page-size` is given. |
32
107
  | `nearby --lat --lng [--radius] [--sort distance\|discovery]` | Venues around a point. |
33
108
  | `place ID [--fields all]` | Full details for one venue. |
34
109
  | `photos ID` | The owner's photo URLs. |
@@ -46,27 +121,30 @@ Flags may use dashes or underscores (`--page-size` = `--page_size`). Bare flags
46
121
  - stdout is always one JSON document: compact when piped, indented on a terminal or with `--pretty`. Progress and the sign-in URL go to stderr.
47
122
  - Errors: `{"ok": false, "error": {"code", "message", "next"?, "details"?}}`. Server codes are passed through (`reservation_time_past`, `reservation_requests_closed`, …).
48
123
  - Exit codes: `0` ok · `1` server/tool error · `2` bad usage · `3` not signed in (run `npx -y heyyumi login`).
49
- - Unknown flags fail with `unknown_option` and a "did you mean" hint instead of being dropped, so a typo never turns into a silently wider search or a nameless booking. Search flags are checked against the live tool schema (cached for an hour).
124
+ - Unknown flags fail with `unknown_option` and a "did you mean" hint instead of being dropped, so a typo never turns into a silently wider search or a nameless booking. Search flags are checked against the live tool schema (cached for an hour), so new server filters work without a CLI update.
50
125
  - When a follow-up command is needed, the output carries `cli.next`, e.g. `npx -y heyyumi wait <id>`.
51
126
 
52
127
  ## Rules for agents
53
128
 
54
- - Only send `reserve` for venues whose result shows `yumiBooking.canRequest: true`. Confirm time, party size, name and phone with the user before sending; it reaches a real venue.
129
+ - Only send `reserve` for venues whose result shows `yumiBooking.canRequest: true`. Confirm time, party size, name and phone with the user before sending; it reaches a real venue. Venues with `requestHours` review requests in those hours (Korea time). A request sent outside them comes back with `cli.deferred: true` and `cli.reviewStartsAt`: it is held, and the guest gets the answer by text or email, so don't wait for it now.
55
130
  - A request starts as `pending`. Say it is booked only after `wait` returns `status: "confirmed"`. `cancelled` means the venue declined (relay `declineReason` if present); `expired` means no answer in time.
56
131
  - `open_at` means the venue is open at that time, not that a table is free. Only a reservation answer says that.
57
132
  - There are no star ratings (`rating` is always null). Do not invent one, and do not attribute review counts to any map platform.
133
+ - `associated_with` results are reported visits with a news link, not endorsements. Say "reportedly visited by".
58
134
  - Link venue names to their `placeUrl`.
59
135
 
60
- ## For k-skill
136
+ ## Use it as an agent skill
61
137
 
62
- A k-skill skill can call this CLI the same way `bunjang-search` calls `bunjang-cli`:
138
+ Any agent or skill system that can run a shell command can wrap this CLI:
63
139
 
64
140
  ```bash
65
- npx -y heyyumi login --client-name k-skill # returns at once if already signed in
141
+ npx -y heyyumi login --client-name "My Agent" # returns at once if already signed in
66
142
  npx -y heyyumi search "<dish or venue>" --region "<area>" --page-size 5
67
143
  ```
68
144
 
69
- Suggested profile: `action:booking` (reservations are irreversible and need the user's approval first). A ready-to-copy skill is in [`integrations/k-skill/heyyumi-restaurant`](integrations/k-skill/heyyumi-restaurant).
145
+ A ready-to-copy skill in the common `SKILL.md` format is in [`examples/agent-skill`](https://github.com/hmp-dev/heyyumi-cli/blob/main/examples/agent-skill/SKILL.md). For Claude Code, copy it to `~/.claude/skills/heyyumi-restaurant/SKILL.md`; for other agents, adapt the same instructions to their skill or tool format. Treat `reserve` and `live` as actions that need the user's approval first, because they reach a real venue.
146
+
147
+ Not in a terminal? The same tools are available as an MCP server for ChatGPT, Claude, Perplexity and Cursor: `https://mcp.heyyumi.ai/mcp` ([setup guide](https://heyyumi.ai/mcp)). Building a product? See the [REST API](https://heyyumi.ai/developers).
70
148
 
71
149
  ## Environment
72
150
 
@@ -80,8 +158,12 @@ Suggested profile: `action:booking` (reservations are irreversible and need the
80
158
 
81
159
  ---
82
160
 
83
- ## 한국어 요약
161
+ **한국어** · AI 에이전트가 터미널 명령 하나로 한국의 검증된 맛집 54만여 곳을 찾고, 매장에 예약 요청까지 보낼 수 있는 CLI입니다. `npx -y heyyumi login`을 한 번 실행해 구글로 로그인하면 바로 쓸 수 있고, 모든 결과는 JSON으로 옵니다. 예약 요청을 보내면 5분 안에 수락 여부를 알 수 있어요.
162
+
163
+ **日本語** · 韓国語が分からなくても、AIエージェントが韓国の飲食店54万件以上から店を探し、予約リクエストまで送れるCLIです。「ビビンバ」のように日本語の料理名でもそのまま検索できます。予約できたかどうかは5分以内に分かります。
164
+
165
+ **中文** · 不会韩语也没关系。这个 CLI 让 AI 助手在韩国 54 万多家经过核实的餐厅、咖啡馆和酒吧中搜索,并直接发送订位请求。可以用中文菜名搜索(例如“拌饭”),5 分钟内就能知道是否订位成功。
84
166
 
85
- AI 에이전트가 터미널 명령 하나로 한국 맛집을 찾고 예약 요청까지 보낼 수 있게 해 주는 CLI입니다. `npx -y heyyumi login`을 한 번 실행하면 브라우저에 구글 로그인 창이 뜨고, 승인하면 그 사용자 전용 키가 만들어져 바로 쓸 수 있습니다. 이후 명령은 모두 JSON으로 답합니다. 예약은 매장이 5분 안에 수락·거절하며, `wait`로 결과를 기다립니다.
167
+ **Español** · Tu IA encuentra y reserva restaurantes reales en Corea sin que sepas coreano: más de 546.000 locales verificados, búsqueda por nombre de plato en tu idioma y solicitudes de reserva con respuesta en 5 minutos.
86
168
 
87
169
  MIT License · © 2026 Hide Me Please, Inc.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "heyyumi",
3
- "version": "0.1.0",
4
- "description": "Find and book real Korean restaurants from your AI agent — no Korean needed. CLI for HeyYumi (search, details, table requests).",
3
+ "version": "0.1.2",
4
+ "description": "Your AI finds and books real Korean restaurants, no Korean needed. 546,000+ verified venues; search, details and table requests as JSON for any agent.",
5
5
  "license": "MIT",
6
6
  "bin": {
7
7
  "heyyumi": "bin/heyyumi.js"
@@ -27,13 +27,22 @@
27
27
  "keywords": [
28
28
  "heyyumi",
29
29
  "korea",
30
+ "korean-food",
31
+ "k-food",
32
+ "seoul",
30
33
  "restaurant",
31
34
  "reservation",
32
- "k-food",
35
+ "booking",
36
+ "travel",
33
37
  "ai-agent",
38
+ "llm",
34
39
  "mcp",
35
40
  "cli",
36
- "k-skill"
41
+ "agent-skills",
42
+ "claude-code",
43
+ "codex",
44
+ "gemini-cli",
45
+ "cursor"
37
46
  ],
38
47
  "publishConfig": {
39
48
  "access": "public"
package/src/commands.js CHANGED
@@ -22,6 +22,26 @@ function pick(obj, key) {
22
22
  return undefined;
23
23
  }
24
24
 
25
+ // A request sent outside the venue's request hours is held until reviewStartsAt, so waiting
26
+ // now would only time out; the guest gets the answer by text or email.
27
+ function withReserveNext(data) {
28
+ const id = pick(data, "reservationId") ?? pick(data, "id");
29
+ if (!id || !data || typeof data !== "object" || Array.isArray(data) || pick(data, "settled") === true) return data;
30
+ const reviewStartsAt = pick(data, "reviewStartsAt");
31
+ if (typeof reviewStartsAt === "string") {
32
+ return {
33
+ ...data,
34
+ cli: {
35
+ deferred: true,
36
+ reviewStartsAt,
37
+ next: `npx -y heyyumi reservation ${id}`,
38
+ note: "Request received outside the venue's request hours. The venue reviews it from reviewStartsAt and the guest gets the result by text or email. Do not wait now; check later with the next command.",
39
+ },
40
+ };
41
+ }
42
+ return { ...data, cli: { next: `npx -y heyyumi wait ${id}` } };
43
+ }
44
+
25
45
  function requirePositional(positionals, name, example) {
26
46
  const v = positionals[0];
27
47
  if (!v) throw usageError(`Missing ${name}. Example: ${example}`);
@@ -188,12 +208,7 @@ const commands = {
188
208
  for (const [flag, key] of Object.entries(optional)) {
189
209
  if (typeof flags[flag] === "string") args[key] = flags[flag];
190
210
  }
191
- const data = await tool("request_reservation", args);
192
- const id = pick(data, "reservationId") ?? pick(data, "id");
193
- if (id && data && typeof data === "object" && !Array.isArray(data) && pick(data, "settled") !== true) {
194
- return { ...data, cli: { next: `npx -y heyyumi wait ${id}` } };
195
- }
196
- return data;
211
+ return withReserveNext(await tool("request_reservation", args));
197
212
  },
198
213
 
199
214
  async reservation({ positionals }) {
@@ -294,4 +309,4 @@ Exit codes: 0 ok · 1 server/tool error · 2 usage · 3 not signed in (run: npx
294
309
  HEYYUMI_API_KEY=hmp_... skips sign-in and uses a dashboard key instead.
295
310
  `;
296
311
 
297
- module.exports = { commands, HELP, pick, checkOwnFlags };
312
+ module.exports = { commands, HELP, pick, checkOwnFlags, withReserveNext };