fitvete-food-cli 1.3.0 → 1.6.0

package/README.md

@@ -38,14 +38,22 @@ export FITVETE_API_KEY=fv_live_your_key
 | `recipe-diets`, `recipe-meal-types`, `recipe-cuisines` | Supported filter values. |
 | `recipe <id> [--servings N]` | Full recipe detail (ingredients, steps, nutrition); optional servings scaler. |
 | `drinks <query...> [--number N]` | Search drinks/cocktails. |
-| `score <name...>\|--barcode CODE [--goals ... --diet ... --allergies ... --avoid ... --explain]` | Personalized 0–100 health score + grade. |
+| `score <name...>\|--barcode CODE\|--id UUID [--goals ... --diet ... --allergies ... --avoid ... --explain]` | Personalized 0–100 health score + grade. |
 | `analyze-ingredients <text...>` | Additives, allergens, NOVA level, diet flags. |
 | `parse <text...>` | Free-text meal → structured items + nutrition (NLP). |
-| `alternatives <name...>\|--barcode CODE [--number N]` | Healthier swaps, ranked. |
+| `alternatives <name...>\|--barcode CODE\|--id UUID [--number N]` | Healthier swaps, ranked. |
 | `foods-autocomplete <query...> [--number N]` | Food name typeahead. |
 | `barcode <code>` | Look up a packaged food by UPC/EAN barcode. |
 | `photo <image-path>` | Estimate meal nutrition from a JPEG, PNG, or WebP image. |
 | `label <image-path>` | Parse a Nutrition Facts label from a JPEG, PNG, or WebP image. |
+| `identify '<json>'` | Unified barcode, text, photo or label identification. |
+| `foods-search <query...>` | Alias for food search. |
+| `food <uuid>` | Read a reference food or one of your private foods. |
+| `create-food '<json>'` | Create a private food with explicit 100 g macros. |
+| `log '<json>'` | Log food_id + grams; server computes nutrition. |
+| `scan <uuid>` | Read your latest scan result (0 points). |
+| `scan-feedback <uuid> '<json>'` | Save a complete correction and expected revision (0 points). |
+| `delete-scan <uuid>` | Delete your scan memory (0 points). |
 | `tools` | Print a JSON tool manifest for AI agents (function-calling). |
 | `help`, `version` | Help / version. |
 
@@ -54,8 +62,12 @@ export FITVETE_API_KEY=fv_live_your_key
 - `--key <key>` — API key (overrides `FITVETE_API_KEY`).
 - `--number, -n <N>` — result count for search commands (1–25).
 - `--base <url>` — API base URL (overrides `FITVETE_API_BASE`).
+- `--timeout <ms>` — request timeout in milliseconds (overrides `FITVETE_API_TIMEOUT`; default `60000`, `none` disables it).
 - `--pretty` — human-readable table instead of JSON.
 - `--json` — force JSON (default).
+- `--version, -v` — print the CLI version.
+
+> `photo` and `label` images must be JPEG, PNG, or WebP and at most 5 MB.
 
 ### Exit codes
 
@@ -80,7 +92,7 @@ The CLI is designed to be driven by autonomous agents:
 - Output is pure JSON — no prompts, spinners, or colour codes.
 - Failures return a non-zero exit code and a JSON error body.
 - `fitvete-food tools` prints a function-calling manifest describing every command
-  and its parameters, so a model can discover the available functions at runtime.
+  and its method/path and parameters, so a model can discover the available functions at runtime.
 
 ```bash
 fitvete-food tools     # → { "tools": [ { "name": "fitvete_search_foods", "input_schema": {...} }, ... ] }
@@ -101,6 +113,23 @@ const run = (cmd, args) => new Promise((res, rej) =>
 
 The same key (`FITVETE_API_KEY`) and JSON contract apply.
 
+## Storage and charging
+
+Private foods/logs require a direct developer key and belong only to its account.
+Scan memory expires after 30 days; management still uses burst limits at 0 points.
+Complete corrections stay private unless explicit contribution consent is supplied.
+Creating foods/logs is not idempotent; do not retry an uncertain creation automatically.
+
+Successful authorization reserves the route's points, including cache hits and
+later handler errors. Invalid image format/size is checked before reservation;
+authentication, quota and burst rejection cost zero. `X-RateLimit-Cost` reports the
+actual reserved cost. See the [current contract](https://fitvete.com/api/docs.html#limits).
+
+Text/photo identification supplies names and estimated portions; the database
+supplies nutrition. A partial text resolution returns null meal totals plus
+`unresolved_items` and `resolved_totals`. Missing measurements are never filled in.
+The CLI never uploads an image larger than 5 MB.
+
 ## License
 
 MIT

package/index.js

@@ -17,14 +17,30 @@
 //
 // Exit codes: 0 ok · 1 request/HTTP error · 2 usage error · 3 auth/limit.
 
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { basename } from "node:path";
 
-const VERSION = "1.3.0";
+const VERSION = "1.6.0";
 const DEFAULT_BASE = "https://auth.fitvete.com/functions/v1/food-api";
 
 // ---- command registry (drives dispatch, --help, and the agent tool manifest) ----
 const COMMANDS = {
+  identify: {summary:"Identify barcode, text, photo or label through one endpoint.",usage:"identify '<JSON>'",args:[{name:"input",type:"string",required:true,description:"JSON type plus barcode/text/image_base64 and content_type."}],options:[],path:()=>"/v1/identify",jsonBody:(a)=>parseJSONArgument(a[0])},
+  food: {summary:"Retrieve a reference or private food by UUID.",usage:"food <id>",args:[{name:"id",type:"string",required:true,description:"Food UUID."}],options:[],path:(a)=>`/v1/foods/${enc(a[0])}`},
+  "create-food": {summary:"Save private per-100g food nutrition.",usage:"create-food '<JSON>'",args:[{name:"food",type:"string",required:true,description:"JSON name, nutrition_basis=100g and complete calorie/macro values."}],options:[],path:()=>"/v1/foods",jsonBody:(a)=>parseJSONArgument(a[0])},
+  log: {summary:"Log grams of a reference or private food.",usage:"log '<JSON>'",args:[{name:"log",type:"string",required:true,description:"JSON food_id, grams and optional logged_at."}],options:[],path:()=>"/v1/logs",jsonBody:(a)=>parseJSONArgument(a[0])},
+  "foods-search": {summary:"Search through the foods resource alias.",usage:"foods-search <query...>",args:[{name:"query",type:"string",required:true,description:"Food name."}],options:[{name:"number",type:"integer",description:"1–25 results."}],path:(a,o)=>`/v1/foods/search?query=${enc(a.join(" "))}${o.number ? `&number=${o.number}` : ""}`},
+  scan: {
+    summary: "Read your private saved scan.", usage: "scan <id>", args: [{name: "id", type: "string", required: true, description: "Scan UUID."}], options: [], path: (a) => `/v1/scans/${enc(a[0])}`,
+  },
+  "delete-scan": {
+    summary: "Delete your private saved scan.", usage: "delete-scan <id>", args: [{name: "id", type: "string", required: true, description: "Scan UUID."}], options: [], method: "DELETE", path: (a) => `/v1/scans/${enc(a[0])}`,
+  },
+  "scan-feedback": {
+    summary: "Correct your scan with complete totals; contribution defaults to private.", usage: "scan-feedback <id> '<JSON>'",
+    args: [{name: "id", type: "string", required: true, description: "Scan UUID."}, {name: "feedback", type: "string", required: true, description: "JSON with scan_revision and correction; consent must be explicit."}], options: [],
+    path: (a) => `/v1/scans/${enc(a[0])}/feedback`, jsonBody: (a) => parseJSONArgument(a[1]),
+  },
   "search-foods": {
     summary: "Search foods by name; returns calories, macros, and confidence.",
     usage: "search-foods <query...> [--number N]",
@@ -174,15 +190,19 @@ const COMMANDS = {
     args: [{ name: "name", type: "string", required: false, description: "Food name (or use --barcode)." }],
     options: [
       { name: "barcode", type: "string", description: "Look up by UPC/EAN instead of name." },
+      { name: "id", type: "string", description: "Reference food UUID, exclusive with name/barcode." },
       { name: "goals", type: "string", description: "Comma-separated, e.g. build muscle,low sugar." },
       { name: "diet", type: "string", description: "e.g. vegan, vegetarian, keto, gluten_free." },
       { name: "allergies", type: "string", description: "Comma-separated allergens." },
       { name: "avoid", type: "string", description: "Comma-separated ingredients to avoid." },
-      { name: "explain", type: "string", description: "Add a natural-language summary (--explain)." },
+      { name: "explain", type: "boolean", description: "Add a natural-language summary (--explain)." },
     ],
+    validate: (a, o) => {
+      if ([o.barcode, o.id, a.join(" ").trim()].filter(Boolean).length !== 1) fail(2, "score needs exactly one food name, --barcode or --id");
+    },
     path: () => "/v1/score",
     jsonBody: (a, o) => ({
-      food: o.barcode ? { barcode: String(o.barcode) } : { name: a.join(" ") },
+      food: o.barcode ? { barcode: String(o.barcode) } : o.id ? {id: String(o.id)} : { name: a.join(" ") },
       profile: buildProfile(o),
       explain: o.explain != null,
     }),
@@ -208,10 +228,13 @@ const COMMANDS = {
     usage: "alternatives <name...>|--barcode CODE [--number N]",
     optionalArgs: true,
     args: [{ name: "name", type: "string", required: false, description: "Food name (or use --barcode)." }],
-    options: [{ name: "barcode", type: "string", description: "Look up by UPC/EAN." }, { name: "number", type: "integer", description: "Max swaps, 1-10 (default 5)." }],
+    options: [{name: "id", type: "string", description: "Food UUID."}, { name: "barcode", type: "string", description: "Look up by UPC/EAN." }, { name: "number", type: "integer", description: "Max swaps, 1-10 (default 5)." }],
+    validate: (a, o) => {
+      if ([o.barcode, o.id, a.join(" ").trim()].filter(Boolean).length !== 1) fail(2, "alternatives needs exactly one food name, --barcode or --id");
+    },
     path: (a, o) => {
       const p = new URLSearchParams();
-      if (o.barcode) p.set("barcode", String(o.barcode)); else p.set("name", a.join(" "));
+      if (o.barcode) p.set("barcode", String(o.barcode)); else if (o.id) p.set("id", String(o.id)); else p.set("name", a.join(" "));
       if (o.number) p.set("number", String(o.number));
       return `/v1/alternatives?${p.toString()}`;
     },
@@ -238,11 +261,32 @@ function buildProfile(o) {
 
 const enc = (s) => encodeURIComponent(s);
 
+const DEFAULT_TIMEOUT_MS = 60000;
+
+// Resolve the request timeout (ms) from --timeout, then FITVETE_API_TIMEOUT, then
+// the default. `0` (or "none") disables the timeout for long-running AI calls.
+function resolveTimeout(flag) {
+  const raw = flag != null ? flag : process.env.FITVETE_API_TIMEOUT;
+  if (raw == null || raw === "") return DEFAULT_TIMEOUT_MS;
+  if (String(raw).toLowerCase() === "none") return 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) fail(2, "--timeout must be a non-negative number of milliseconds (or 'none')");
+  return n;
+}
+
+function parseJSONArgument(value) {
+  try { const parsed = JSON.parse(value); if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(); return parsed; }
+  catch { fail(2, "a valid JSON object argument is required"); }
+}
 function fail(code, msg) {
   process.stderr.write(`fitvete-food: ${msg}\n`);
+  process.stdout.write(JSON.stringify({status: "failure", code: code === 3 ? 401 : code === 2 ? 400 : 502, message: msg}) + "\n");
   process.exit(code);
 }
 
+// Flags that never take a value (must not swallow the following positional).
+const BOOLEAN_FLAGS = new Set(["pretty", "json", "help", "version", "explain"]);
+
 // ---- argv parsing: positionals + --flags (--key, --base, --number, --pretty, --json) ----
 function parseArgs(argv) {
   const pos = [];
@@ -258,12 +302,17 @@ function parseArgs(argv) {
     else if (a.startsWith("--key=")) opts.key = a.slice(6);
     else if (a.startsWith("--base=")) opts.base = a.slice(7);
     else if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "-v" || a === "--version") opts.version = true;
     // Generic --flag value / --flag=value (recipe filters etc.), kebab -> camelCase.
     else if (a.startsWith("--")) {
       const eq = a.indexOf("=");
       const rawKey = eq >= 0 ? a.slice(2, eq) : a.slice(2);
-      const val = eq >= 0 ? a.slice(eq + 1) : (argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : "true");
-      opts[rawKey.replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = val;
+      const key = rawKey.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      // Boolean flags never consume the next token; everyone else takes --flag value.
+      const val = eq >= 0
+        ? a.slice(eq + 1)
+        : (!BOOLEAN_FLAGS.has(key) && argv[i + 1] != null && !argv[i + 1].startsWith("--") ? argv[++i] : "true");
+      opts[key] = val;
     }
     else if (a.startsWith("-") && a !== "-") fail(2, `unknown option: ${a}`);
     else pos.push(a);
@@ -285,18 +334,22 @@ function helpText() {
     "",
     "Commands:",
   ];
-  for (const [name, c] of Object.entries(COMMANDS)) lines.push(`  ${name.padEnd(14)} ${c.summary}`);
+  const names = [...Object.keys(COMMANDS), "tools", "help", "version"];
+  const w = Math.max(...names.map((n) => n.length));
+  for (const [name, c] of Object.entries(COMMANDS)) lines.push(`  ${name.padEnd(w)}  ${c.summary}`);
   lines.push(
-    "  tools          Print a JSON tool manifest for AI agents (function-calling).",
-    "  help           Show this help.",
-    "  version        Print the CLI version.",
+    `  ${"tools".padEnd(w)}  Print a JSON tool manifest for AI agents (function-calling).`,
+    `  ${"help".padEnd(w)}  Show this help.`,
+    `  ${"version".padEnd(w)}  Print the CLI version.`,
     "",
     "Options:",
-    "  --key <key>    API key (overrides FITVETE_API_KEY).",
-    "  --number, -n   Max results for search commands (1-25).",
-    "  --base <url>   API base URL (overrides FITVETE_API_BASE).",
-    "  --pretty       Human-readable table instead of JSON.",
-    "  --json         Force JSON output (default).",
+    "  --key <key>      API key (overrides FITVETE_API_KEY).",
+    "  --number, -n     Max results for search commands (1-25).",
+    "  --base <url>     API base URL (overrides FITVETE_API_BASE).",
+    "  --timeout <ms>   Request timeout in ms (default 60000; 'none' to disable).",
+    "  --pretty         Human-readable table instead of JSON.",
+    "  --json           Force JSON output (default).",
+    "  --version, -v    Print the CLI version.",
     "",
     "Auth: set FITVETE_API_KEY or pass --key. Get a free key at https://fitvete.com/api/",
     "",
@@ -310,6 +363,37 @@ function helpText() {
   return lines.join("\n");
 }
 
+const COMMAND_ROUTES = {
+  "identify": "/v1/identify",
+  "food": "/v1/foods/{id}",
+  "create-food": "/v1/foods",
+  "log": "/v1/logs",
+  "foods-search": "/v1/foods/search",
+  "scan": "/v1/scans/{id}",
+  "delete-scan": "/v1/scans/{id}",
+  "scan-feedback": "/v1/scans/{id}/feedback",
+  "search-foods": "/v1/search-foods",
+  "compute": "/v1/compute-nutrition",
+  "recipes": "/v1/recipes/search",
+  "recipe-random": "/v1/recipes/random",
+  "recipe-autocomplete": "/v1/recipes/autocomplete",
+  "recipe-similar": "/v1/recipes/{id}/similar",
+  "recipes-by-nutrients": "/v1/recipes/by-nutrients",
+  "recipe-diets": "/v1/recipes/diets",
+  "recipe-meal-types": "/v1/recipes/meal-types",
+  "recipe-cuisines": "/v1/recipes/cuisines",
+  "recipe": "/v1/recipes/{id}",
+  "drinks": "/v1/drinks/search",
+  "barcode": "/v1/barcode/{code}",
+  "photo": "/v1/nutrition-from-photo",
+  "label": "/v1/nutrition-label",
+  "score": "/v1/score",
+  "analyze-ingredients": "/v1/analyze-ingredients",
+  "parse": "/v1/parse",
+  "alternatives": "/v1/alternatives",
+  "foods-autocomplete": "/v1/foods/autocomplete"
+};
+
 // AI-agent tool manifest: every command as a function-calling tool definition.
 function toolManifest() {
   const tools = Object.entries(COMMANDS).map(([name, c]) => {
@@ -319,10 +403,12 @@ function toolManifest() {
       properties[a.name] = { type: a.type === "integer" ? "integer" : "string", description: a.description };
       if (a.required) required.push(a.name);
     }
-    for (const o of c.options) properties[o.name] = { type: o.type === "integer" ? "integer" : "string", description: o.description };
+    for (const o of c.options) properties[o.name] = { type: o.type, description: o.description };
     return {
       name: `fitvete_${name.replace(/-/g, "_")}`,
       command: name,
+      method: c.method || (c.jsonBody ? "POST" : "GET"),
+      path: COMMAND_ROUTES[name],
       description: c.summary,
       cli: `fitvete-food ${c.usage}`,
       input_schema: { type: "object", properties, required },
@@ -358,12 +444,16 @@ async function request(spec, args, opts) {
   };
   if (spec.jsonBody) {
     init.headers["content-type"] = "application/json";
-    init.body = JSON.stringify(spec.jsonBody(args, opts));
+    const payload = spec.jsonBody(args, opts);
+    if (typeof payload.image_base64 === "string" && Buffer.byteLength(payload.image_base64, "base64") > 5 * 1024 * 1024) fail(2, "image exceeds 5 MB");
+    init.body = JSON.stringify(payload);
   } else if (spec.imageArg) {
     const filePath = args[0];
     let bytes;
     try {
+      if ((await stat(filePath)).size > 5 * 1024 * 1024) fail(2, "image exceeds 5 MB");
       bytes = await readFile(filePath);
+      if (bytes.length > 5 * 1024 * 1024) fail(2, "image exceeds 5 MB");
     } catch (e) {
       fail(2, `cannot read image file: ${e.message}`);
     }
@@ -371,10 +461,15 @@ async function request(spec, args, opts) {
     form.append("image", new Blob([bytes], { type: mimeType(filePath) }), basename(filePath));
     init.body = form;
   }
+  const timeoutMs = resolveTimeout(opts.timeout);
+  if (timeoutMs) init.signal = AbortSignal.timeout(timeoutMs);
   let res;
   try {
     res = await fetch(base + path, init);
   } catch (e) {
+    if (e && (e.name === "TimeoutError" || e.name === "AbortError")) {
+      fail(1, `request timed out after ${timeoutMs}ms (raise it with --timeout or FITVETE_API_TIMEOUT)`);
+    }
     fail(1, `network error: ${e.message}`);
   }
   const text = await res.text();
@@ -426,13 +521,14 @@ function pretty(command, data) {
 const { pos, opts } = parseArgs(process.argv.slice(2));
 const command = pos.shift();
 
+if (opts.version || command === "version") { process.stdout.write(VERSION + "\n"); process.exit(0); }
 if (!command || command === "help" || opts.help) { process.stdout.write(helpText() + "\n"); process.exit(0); }
-if (command === "version" || command === "--version" || command === "-v") { process.stdout.write(VERSION + "\n"); process.exit(0); }
 if (command === "tools") { process.stdout.write(JSON.stringify(toolManifest(), null, 2) + "\n"); process.exit(0); }
 
 const spec = COMMANDS[command];
 if (!spec) fail(2, `unknown command: ${command}. Run 'fitvete-food help'.`);
 if (pos.length === 0 && !spec.optionalArgs) fail(2, `usage: fitvete-food ${spec.usage}`);
+if (spec.validate) spec.validate(pos, opts);
 
 const data = await request(spec, pos, opts);
 process.stdout.write((opts.pretty ? pretty(command, data) : JSON.stringify(data)) + "\n");

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "fitvete-food-cli",
-  "version": "1.3.0",
+  "version": "1.6.0",
   "description": "CLI for the FitVete Food & Nutrition API — clean JSON output for scripts and AI agents.",
   "bin": {
-    "fitvete-food": "index.js"
+    "fitvete-food": "index.js",
+    "fitvete-food-cli": "index.js"
   },
   "type": "module",
   "engines": {