heyyumi 0.1.1 → 0.1.3
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 +11 -18
- package/package.json +2 -2
- package/src/commands.js +66 -9
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
**Your AI finds and books real Korean restaurants, no Korean needed.**
|
|
8
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 **
|
|
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
10
|
|
|
11
11
|
```bash
|
|
12
12
|
npx -y heyyumi login # once: Google sign-in in the browser, a key is made for you
|
|
@@ -18,7 +18,7 @@ Works with any agent that runs shell commands and reads JSON: Claude Code, Codex
|
|
|
18
18
|
|
|
19
19
|
## What your agent gets
|
|
20
20
|
|
|
21
|
-
**Real data, cross-checked.**
|
|
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
22
|
|
|
23
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
24
|
|
|
@@ -59,7 +59,7 @@ $ npx -y heyyumi search bibimbap --region Myeongdong --page-size 3 --fields core
|
|
|
59
59
|
"distanceM": 241,
|
|
60
60
|
"placeUrl": "https://heyyumi.ai/en/places/8392850",
|
|
61
61
|
"matchReason": "name",
|
|
62
|
-
"yumiBooking": { "canRequest": true
|
|
62
|
+
"yumiBooking": { "canRequest": true }
|
|
63
63
|
},
|
|
64
64
|
{
|
|
65
65
|
"name": "방이옥 종로점",
|
|
@@ -109,9 +109,10 @@ npx -y heyyumi place <placeId> --fields all # menu, hours, attributes,
|
|
|
109
109
|
| `photos ID` | The owner's photo URLs. |
|
|
110
110
|
| `regions NAME` · `categories` · `stats` | Region lookup, category list, coverage numbers. |
|
|
111
111
|
| `reserve ID --time --party --phone [--name --email --note --lang]` | Send a table request. Times without an offset are Korea time. `--email` is required for non-Korean phone numbers. |
|
|
112
|
-
| `wait RESERVATION_ID [--timeout 110]` | Wait for the venue's answer
|
|
112
|
+
| `wait RESERVATION_ID [--timeout 110]` | Wait for the venue's answer. Re-run if `cli.settled` is false. |
|
|
113
113
|
| `reservation RESERVATION_ID` | Check a request once. |
|
|
114
114
|
| `live ID --kind item\|wait\|seats --topic TEXT` · `live-wait QUERY_ID` | Ask the venue right now (stock, wait time, seats). |
|
|
115
|
+
| `guide [search\|place\|reserve\|live]` | Rules for agents, served by HeyYumi and always current. |
|
|
115
116
|
| `tools [TOOL]` · `call TOOL --json '{...}'` | Raw access to every HeyYumi MCP tool. |
|
|
116
117
|
|
|
117
118
|
Flags may use dashes or underscores (`--page-size` = `--page_size`). Bare flags mean `true`.
|
|
@@ -119,30 +120,22 @@ Flags may use dashes or underscores (`--page-size` = `--page_size`). Bare flags
|
|
|
119
120
|
## Output contract
|
|
120
121
|
|
|
121
122
|
- 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.
|
|
122
|
-
- Errors: `{"ok": false, "error": {"code", "message", "next"?, "details"?}}`. Server codes are passed through
|
|
123
|
+
- Errors: `{"ok": false, "error": {"code", "message", "next"?, "details"?}}`. Server error codes and messages are passed through.
|
|
123
124
|
- Exit codes: `0` ok · `1` server/tool error · `2` bad usage · `3` not signed in (run `npx -y heyyumi login`).
|
|
124
125
|
- 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.
|
|
125
126
|
- When a follow-up command is needed, the output carries `cli.next`, e.g. `npx -y heyyumi wait <id>`.
|
|
126
127
|
|
|
127
|
-
## Rules for agents
|
|
128
|
-
|
|
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` take requests only in those hours (Korea time).
|
|
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.
|
|
131
|
-
- `open_at` means the venue is open at that time, not that a table is free. Only a reservation answer says that.
|
|
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".
|
|
134
|
-
- Link venue names to their `placeUrl`.
|
|
135
|
-
|
|
136
128
|
## Use it as an agent skill
|
|
137
129
|
|
|
138
|
-
Any agent or skill system that can run a shell command can wrap this CLI:
|
|
130
|
+
Any agent or skill system that can run a shell command can wrap this CLI. The usage rules come from the HeyYumi server, so a skill never goes out of date:
|
|
139
131
|
|
|
140
132
|
```bash
|
|
141
133
|
npx -y heyyumi login --client-name "My Agent" # returns at once if already signed in
|
|
142
|
-
npx -y heyyumi
|
|
134
|
+
npx -y heyyumi guide # rules for agents, read once per task
|
|
135
|
+
npx -y heyyumi guide reserve # before sending a table request
|
|
143
136
|
```
|
|
144
137
|
|
|
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,
|
|
138
|
+
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, point their skill at `npx -y heyyumi guide`. Treat `reserve` and `live` as actions that need the user's approval first, because they reach a real venue.
|
|
146
139
|
|
|
147
140
|
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).
|
|
148
141
|
|
|
@@ -164,6 +157,6 @@ Not in a terminal? The same tools are available as an MCP server for ChatGPT, Cl
|
|
|
164
157
|
|
|
165
158
|
**中文** · 不会韩语也没关系。这个 CLI 让 AI 助手在韩国 54 万多家经过核实的餐厅、咖啡馆和酒吧中搜索,并直接发送订位请求。可以用中文菜名搜索(例如“拌饭”),5 分钟内就能知道是否订位成功。
|
|
166
159
|
|
|
167
|
-
**Español** · Tu IA encuentra y reserva restaurantes reales en Corea sin que sepas coreano: más de
|
|
160
|
+
**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.
|
|
168
161
|
|
|
169
162
|
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": "Your AI finds and books real Korean restaurants, no Korean needed.
|
|
3
|
+
"version": "0.1.3",
|
|
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"
|
package/src/commands.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
|
|
3
3
|
const { flagsToToolArgs } = require("./args");
|
|
4
|
-
const { callTool, listTools } = require("./mcp");
|
|
4
|
+
const { callTool, listTools, rpc } = require("./mcp");
|
|
5
5
|
const { login } = require("./oauth");
|
|
6
6
|
const { readCredentials, removeCredentials } = require("./credentials");
|
|
7
7
|
const { normalizeReservationTime } = require("./time");
|
|
@@ -22,6 +22,25 @@ function pick(obj, key) {
|
|
|
22
22
|
return undefined;
|
|
23
23
|
}
|
|
24
24
|
|
|
25
|
+
// A held request is only reviewed from reviewStartsAt, so waiting now would just time out.
|
|
26
|
+
function withReserveNext(data) {
|
|
27
|
+
const id = pick(data, "reservationId") ?? pick(data, "id");
|
|
28
|
+
if (!id || !data || typeof data !== "object" || Array.isArray(data) || pick(data, "settled") === true) return data;
|
|
29
|
+
const reviewStartsAt = pick(data, "reviewStartsAt");
|
|
30
|
+
if (typeof reviewStartsAt === "string") {
|
|
31
|
+
return {
|
|
32
|
+
...data,
|
|
33
|
+
cli: {
|
|
34
|
+
deferred: true,
|
|
35
|
+
reviewStartsAt,
|
|
36
|
+
next: `npx -y heyyumi reservation ${id}`,
|
|
37
|
+
note: "The request is held for later. Pass on yumiNextStep and don't wait now.",
|
|
38
|
+
},
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
return { ...data, cli: { next: `npx -y heyyumi wait ${id}` } };
|
|
42
|
+
}
|
|
43
|
+
|
|
25
44
|
function requirePositional(positionals, name, example) {
|
|
26
45
|
const v = positionals[0];
|
|
27
46
|
if (!v) throw usageError(`Missing ${name}. Example: ${example}`);
|
|
@@ -61,6 +80,21 @@ function timeoutFlag(flags, fallback) {
|
|
|
61
80
|
return n;
|
|
62
81
|
}
|
|
63
82
|
|
|
83
|
+
// The server's rules name MCP tools; agents run these CLI commands instead.
|
|
84
|
+
const CLI_FOR_TOOL = {
|
|
85
|
+
search_places: "npx -y heyyumi search",
|
|
86
|
+
nearby_places: "npx -y heyyumi nearby",
|
|
87
|
+
get_place: "npx -y heyyumi place",
|
|
88
|
+
show_place_photos: "npx -y heyyumi photos",
|
|
89
|
+
resolve_regions: "npx -y heyyumi regions",
|
|
90
|
+
request_reservation: "npx -y heyyumi reserve",
|
|
91
|
+
wait_for_reservation: "npx -y heyyumi wait",
|
|
92
|
+
get_reservation: "npx -y heyyumi reservation",
|
|
93
|
+
request_live_status: "npx -y heyyumi live",
|
|
94
|
+
wait_for_live_status: "npx -y heyyumi live-wait",
|
|
95
|
+
};
|
|
96
|
+
const GUIDE_TOPICS = { search: "search_places", place: "get_place", reserve: "request_reservation", live: "request_live_status" };
|
|
97
|
+
|
|
64
98
|
// Commands that build tool arguments by hand. Anything else they get is a typo, and a dropped
|
|
65
99
|
// `--nme` would book under no name, so reject it. Commands not listed forward flags to the tool,
|
|
66
100
|
// where validateArgs checks them against the live schema.
|
|
@@ -77,6 +111,7 @@ const OWN_FLAGS = {
|
|
|
77
111
|
live: ["kind", "topic", "question"],
|
|
78
112
|
"live-wait": ["timeout"],
|
|
79
113
|
tools: [],
|
|
114
|
+
guide: [],
|
|
80
115
|
version: [],
|
|
81
116
|
};
|
|
82
117
|
const OUTPUT_FLAGS = ["pretty", "compact", "help"];
|
|
@@ -188,12 +223,7 @@ const commands = {
|
|
|
188
223
|
for (const [flag, key] of Object.entries(optional)) {
|
|
189
224
|
if (typeof flags[flag] === "string") args[key] = flags[flag];
|
|
190
225
|
}
|
|
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;
|
|
226
|
+
return withReserveNext(await tool("request_reservation", args));
|
|
197
227
|
},
|
|
198
228
|
|
|
199
229
|
async reservation({ positionals }) {
|
|
@@ -255,6 +285,29 @@ const commands = {
|
|
|
255
285
|
return tool(name, args);
|
|
256
286
|
},
|
|
257
287
|
|
|
288
|
+
async guide({ positionals }) {
|
|
289
|
+
const topic = positionals[0];
|
|
290
|
+
if (topic !== undefined) {
|
|
291
|
+
const toolName = GUIDE_TOPICS[topic];
|
|
292
|
+
if (!toolName) throw usageError(`Unknown guide topic "${topic}". Topics: ${Object.keys(GUIDE_TOPICS).join(", ")}`);
|
|
293
|
+
const t = (await listTools()).find((x) => x.name === toolName);
|
|
294
|
+
if (!t) throw new CliError("tool_not_found", `The server has no ${toolName} tool right now.`);
|
|
295
|
+
return { ok: true, topic, command: CLI_FOR_TOOL[toolName], rules: t.description };
|
|
296
|
+
}
|
|
297
|
+
const init = await rpc("initialize", {
|
|
298
|
+
protocolVersion: "2025-06-18",
|
|
299
|
+
capabilities: {},
|
|
300
|
+
clientInfo: { name: "heyyumi-cli", version },
|
|
301
|
+
});
|
|
302
|
+
return {
|
|
303
|
+
ok: true,
|
|
304
|
+
instructions: init?.instructions || "",
|
|
305
|
+
commands: CLI_FOR_TOOL,
|
|
306
|
+
topics: Object.fromEntries(Object.keys(GUIDE_TOPICS).map((k) => [k, `npx -y heyyumi guide ${k}`])),
|
|
307
|
+
note: "These rules come from the HeyYumi server and stay current. They name MCP tools; run the matching command from `commands` (reserve takes --time --party --phone --name --email --note --lang). Read `guide reserve` before sending a table request and `guide live` before asking a venue.",
|
|
308
|
+
};
|
|
309
|
+
},
|
|
310
|
+
|
|
258
311
|
async version() {
|
|
259
312
|
return { ok: true, version };
|
|
260
313
|
},
|
|
@@ -266,6 +319,10 @@ Sign in (once per machine; opens Google sign-in, finishes on its own):
|
|
|
266
319
|
heyyumi login [--no-browser] [--client-name NAME] [--timeout 300] [--force]
|
|
267
320
|
heyyumi status | logout
|
|
268
321
|
|
|
322
|
+
Rules for agents (from the server, always current):
|
|
323
|
+
heyyumi guide read once per task
|
|
324
|
+
heyyumi guide search|place|reserve|live rules for one step
|
|
325
|
+
|
|
269
326
|
Search & details:
|
|
270
327
|
heyyumi search [KEYWORD] --region 을지로 [--subtype korean_bbq] [--open_at "2026-10-25 19:00"] [--parking] ...
|
|
271
328
|
Any search_places filter works as a flag (see: heyyumi tools search_places). 10 results unless --page-size.
|
|
@@ -275,7 +332,7 @@ Search & details:
|
|
|
275
332
|
heyyumi photos PLACE_ID
|
|
276
333
|
heyyumi regions NAME | categories | stats
|
|
277
334
|
|
|
278
|
-
Table requests (
|
|
335
|
+
Table requests (read "heyyumi guide reserve" first; ask the user before sending):
|
|
279
336
|
heyyumi reserve PLACE_ID --time "2026-10-25 19:00" --party 2 --phone 010-1234-5678 [--name NAME]
|
|
280
337
|
[--email EMAIL (required for non-Korean phones)] [--note TEXT] [--lang en]
|
|
281
338
|
heyyumi wait RESERVATION_ID [--timeout 110] waits until confirmed / cancelled / expired (venue has 5 min)
|
|
@@ -294,4 +351,4 @@ Exit codes: 0 ok · 1 server/tool error · 2 usage · 3 not signed in (run: npx
|
|
|
294
351
|
HEYYUMI_API_KEY=hmp_... skips sign-in and uses a dashboard key instead.
|
|
295
352
|
`;
|
|
296
353
|
|
|
297
|
-
module.exports = { commands, HELP, pick, checkOwnFlags };
|
|
354
|
+
module.exports = { commands, HELP, pick, checkOwnFlags, withReserveNext };
|