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 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, "requestHours": "10:00-20:00 KST" }
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` | The owner's photo URLs. |
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 (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` 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 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
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "heyyumi",
3
- "version": "0.1.2",
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 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.
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: "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.",
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
- // Photo URLs via get_place; the photo tool returns base64 thumbnails, which do not belong in a terminal.
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
- return tool("get_place", { id, fields: "photos" });
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 (only where a result shows yumiBooking.canRequest=true; ask the user before sending):
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 };