heyyumi 0.1.2 → 0.1.4
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 +9 -16
- package/package.json +1 -1
- package/src/commands.js +81 -11
package/README.md
CHANGED
|
@@ -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": "방이옥 종로점",
|
|
@@ -106,12 +106,13 @@ npx -y heyyumi place <placeId> --fields all # menu, hours, attributes,
|
|
|
106
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. |
|
|
107
107
|
| `nearby --lat --lng [--radius] [--sort distance\|discovery]` | Venues around a point. |
|
|
108
108
|
| `place ID [--fields all]` | Full details for one venue. |
|
|
109
|
-
| `photos ID` |
|
|
109
|
+
| `photos ID` | Photo URLs: the owner's, plus food photos and videos from credited creators (with their @handle and post link). |
|
|
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` 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.
|
|
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
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "heyyumi",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.4",
|
|
4
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": {
|
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,8 +22,7 @@ function pick(obj, key) {
|
|
|
22
22
|
return undefined;
|
|
23
23
|
}
|
|
24
24
|
|
|
25
|
-
// A request
|
|
26
|
-
// now would only time out; the guest gets the answer by text or email.
|
|
25
|
+
// A held request is only reviewed from reviewStartsAt, so waiting now would just time out.
|
|
27
26
|
function withReserveNext(data) {
|
|
28
27
|
const id = pick(data, "reservationId") ?? pick(data, "id");
|
|
29
28
|
if (!id || !data || typeof data !== "object" || Array.isArray(data) || pick(data, "settled") === true) return data;
|
|
@@ -35,7 +34,7 @@ function withReserveNext(data) {
|
|
|
35
34
|
deferred: true,
|
|
36
35
|
reviewStartsAt,
|
|
37
36
|
next: `npx -y heyyumi reservation ${id}`,
|
|
38
|
-
note: "
|
|
37
|
+
note: "The request is held for later. Pass on yumiNextStep and don't wait now.",
|
|
39
38
|
},
|
|
40
39
|
};
|
|
41
40
|
}
|
|
@@ -81,6 +80,42 @@ function timeoutFlag(flags, fallback) {
|
|
|
81
80
|
return n;
|
|
82
81
|
}
|
|
83
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 = {
|
|
97
|
+
search: "search_places",
|
|
98
|
+
place: "get_place",
|
|
99
|
+
photos: "show_place_photos",
|
|
100
|
+
reserve: "request_reservation",
|
|
101
|
+
live: "request_live_status",
|
|
102
|
+
};
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* show_place_photos answers with one JSON block plus base64 thumbnails. A terminal agent gets the JSON
|
|
106
|
+
* (full-size urls, credit, postUrl, videoUrl, ambassadorPosts, the server note) and no thumbnails.
|
|
107
|
+
*/
|
|
108
|
+
function photosResult(data) {
|
|
109
|
+
const parts = Array.isArray(data) ? data : [data];
|
|
110
|
+
const json = parts.find((p) => p && typeof p === "object" && p.type !== "image") || {};
|
|
111
|
+
return {
|
|
112
|
+
...json,
|
|
113
|
+
cli: {
|
|
114
|
+
note: "Thumbnails are left out of CLI output. Show each photo `url` as a link; for items with `credit`, put the credit next to the photo and link `postUrl`.",
|
|
115
|
+
},
|
|
116
|
+
};
|
|
117
|
+
}
|
|
118
|
+
|
|
84
119
|
// Commands that build tool arguments by hand. Anything else they get is a typo, and a dropped
|
|
85
120
|
// `--nme` would book under no name, so reject it. Commands not listed forward flags to the tool,
|
|
86
121
|
// where validateArgs checks them against the live schema.
|
|
@@ -88,7 +123,7 @@ const OWN_FLAGS = {
|
|
|
88
123
|
login: ["client-name", "no-browser", "timeout", "force"],
|
|
89
124
|
logout: [],
|
|
90
125
|
status: [],
|
|
91
|
-
photos: [],
|
|
126
|
+
photos: ["category", "limit"],
|
|
92
127
|
categories: [],
|
|
93
128
|
stats: [],
|
|
94
129
|
reserve: ["time", "party", "phone", "name", "email", "note", "lang", "idempotency-key"],
|
|
@@ -97,6 +132,7 @@ const OWN_FLAGS = {
|
|
|
97
132
|
live: ["kind", "topic", "question"],
|
|
98
133
|
"live-wait": ["timeout"],
|
|
99
134
|
tools: [],
|
|
135
|
+
guide: [],
|
|
100
136
|
version: [],
|
|
101
137
|
};
|
|
102
138
|
const OUTPUT_FLAGS = ["pretty", "compact", "help"];
|
|
@@ -171,10 +207,17 @@ const commands = {
|
|
|
171
207
|
return tool("get_place", { id, ...flagsToToolArgs(flags) });
|
|
172
208
|
},
|
|
173
209
|
|
|
174
|
-
//
|
|
175
|
-
async photos({ positionals }) {
|
|
210
|
+
// The photo tool also lists ambassador photos with their credit, and says what to do when there are none.
|
|
211
|
+
async photos({ positionals, flags }) {
|
|
176
212
|
const id = requirePositional(positionals, "place id", "heyyumi photos 21853004");
|
|
177
|
-
|
|
213
|
+
const args = { id };
|
|
214
|
+
if (flags.category !== undefined) args.category = String(flags.category);
|
|
215
|
+
if (flags.limit !== undefined) {
|
|
216
|
+
const n = Number(flags.limit);
|
|
217
|
+
if (!Number.isInteger(n) || n < 1) throw usageError("--limit must be a whole number, e.g. --limit 6");
|
|
218
|
+
args.limit = n;
|
|
219
|
+
}
|
|
220
|
+
return photosResult(await tool("show_place_photos", args));
|
|
178
221
|
},
|
|
179
222
|
|
|
180
223
|
async regions({ positionals, flags }) {
|
|
@@ -270,6 +313,29 @@ const commands = {
|
|
|
270
313
|
return tool(name, args);
|
|
271
314
|
},
|
|
272
315
|
|
|
316
|
+
async guide({ positionals }) {
|
|
317
|
+
const topic = positionals[0];
|
|
318
|
+
if (topic !== undefined) {
|
|
319
|
+
const toolName = GUIDE_TOPICS[topic];
|
|
320
|
+
if (!toolName) throw usageError(`Unknown guide topic "${topic}". Topics: ${Object.keys(GUIDE_TOPICS).join(", ")}`);
|
|
321
|
+
const t = (await listTools()).find((x) => x.name === toolName);
|
|
322
|
+
if (!t) throw new CliError("tool_not_found", `The server has no ${toolName} tool right now.`);
|
|
323
|
+
return { ok: true, topic, command: CLI_FOR_TOOL[toolName], rules: t.description };
|
|
324
|
+
}
|
|
325
|
+
const init = await rpc("initialize", {
|
|
326
|
+
protocolVersion: "2025-06-18",
|
|
327
|
+
capabilities: {},
|
|
328
|
+
clientInfo: { name: "heyyumi-cli", version },
|
|
329
|
+
});
|
|
330
|
+
return {
|
|
331
|
+
ok: true,
|
|
332
|
+
instructions: init?.instructions || "",
|
|
333
|
+
commands: CLI_FOR_TOOL,
|
|
334
|
+
topics: Object.fromEntries(Object.keys(GUIDE_TOPICS).map((k) => [k, `npx -y heyyumi guide ${k}`])),
|
|
335
|
+
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; photos takes --category --limit). Read `guide reserve` before sending a table request and `guide live` before asking a venue.",
|
|
336
|
+
};
|
|
337
|
+
},
|
|
338
|
+
|
|
273
339
|
async version() {
|
|
274
340
|
return { ok: true, version };
|
|
275
341
|
},
|
|
@@ -281,16 +347,20 @@ Sign in (once per machine; opens Google sign-in, finishes on its own):
|
|
|
281
347
|
heyyumi login [--no-browser] [--client-name NAME] [--timeout 300] [--force]
|
|
282
348
|
heyyumi status | logout
|
|
283
349
|
|
|
350
|
+
Rules for agents (from the server, always current):
|
|
351
|
+
heyyumi guide read once per task
|
|
352
|
+
heyyumi guide search|place|photos|reserve|live rules for one step
|
|
353
|
+
|
|
284
354
|
Search & details:
|
|
285
355
|
heyyumi search [KEYWORD] --region 을지로 [--subtype korean_bbq] [--open_at "2026-10-25 19:00"] [--parking] ...
|
|
286
356
|
Any search_places filter works as a flag (see: heyyumi tools search_places). 10 results unless --page-size.
|
|
287
357
|
--region takes Korean or romanized names, stations and landmarks (Hongdae, 강남역, 제주공항).
|
|
288
358
|
heyyumi nearby --lat 37.5665 --lng 126.978 [--radius 800] [--sort discovery]
|
|
289
359
|
heyyumi place PLACE_ID [--fields all]
|
|
290
|
-
heyyumi photos PLACE_ID
|
|
360
|
+
heyyumi photos PLACE_ID [--limit 6] [--category interior]
|
|
291
361
|
heyyumi regions NAME | categories | stats
|
|
292
362
|
|
|
293
|
-
Table requests (
|
|
363
|
+
Table requests (read "heyyumi guide reserve" first; ask the user before sending):
|
|
294
364
|
heyyumi reserve PLACE_ID --time "2026-10-25 19:00" --party 2 --phone 010-1234-5678 [--name NAME]
|
|
295
365
|
[--email EMAIL (required for non-Korean phones)] [--note TEXT] [--lang en]
|
|
296
366
|
heyyumi wait RESERVATION_ID [--timeout 110] waits until confirmed / cancelled / expired (venue has 5 min)
|
|
@@ -309,4 +379,4 @@ Exit codes: 0 ok · 1 server/tool error · 2 usage · 3 not signed in (run: npx
|
|
|
309
379
|
HEYYUMI_API_KEY=hmp_... skips sign-in and uses a dashboard key instead.
|
|
310
380
|
`;
|
|
311
381
|
|
|
312
|
-
module.exports = { commands, HELP, pick, checkOwnFlags, withReserveNext };
|
|
382
|
+
module.exports = { commands, HELP, pick, checkOwnFlags, withReserveNext, photosResult };
|