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.
- package/README.md +100 -18
- package/package.json +13 -4
- package/src/commands.js +22 -7
package/README.md
CHANGED
|
@@ -1,18 +1,93 @@
|
|
|
1
1
|
# heyyumi
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/heyyumi)
|
|
4
|
+
[](https://www.npmjs.com/package/heyyumi)
|
|
5
|
+
[](https://github.com/hmp-dev/heyyumi-cli/blob/main/LICENSE)
|
|
4
6
|
|
|
5
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
##
|
|
136
|
+
## Use it as an agent skill
|
|
61
137
|
|
|
62
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
4
|
-
"description": "
|
|
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
|
-
"
|
|
35
|
+
"booking",
|
|
36
|
+
"travel",
|
|
33
37
|
"ai-agent",
|
|
38
|
+
"llm",
|
|
34
39
|
"mcp",
|
|
35
40
|
"cli",
|
|
36
|
-
"
|
|
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
|
-
|
|
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 };
|