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 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 **543,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.
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.** 367,000+ restaurants, 138,000+ cafes and 36,000+ bars. More than 424,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".
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, "requestHours": "11:00-21:00 KST" }
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 (they have 5 minutes). Re-run if `cli.settled` is false. |
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 (`reservation_time_past`, `reservation_requests_closed`, …).
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 search "<dish or venue>" --region "<area>" --page-size 5
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, 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.
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 543.000 locales verificados, búsqueda por nombre de plato en tu idioma y solicitudes de reserva con respuesta en 5 minutos.
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.1",
4
- "description": "Your AI finds and books real Korean restaurants, no Korean needed. 543,000+ verified venues; search, details and table requests as JSON for any agent.",
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
- 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;
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 (only where a result shows yumiBooking.canRequest=true; ask the user before sending):
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 };