fitvete-food-cli 1.4.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. |
 
@@ -84,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": {...} }, ... ] }
@@ -105,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.4.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,18 +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 && a.join(" ").trim() === "") fail(2, "score needs a food name or --barcode CODE");
+      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,
     }),
@@ -211,13 +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 && a.join(" ").trim() === "") fail(2, "alternatives needs a food name or --barcode CODE");
+      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()}`;
     },
@@ -257,8 +274,13 @@ function resolveTimeout(flag) {
   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);
 }
 
@@ -341,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]) => {
@@ -350,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 },
@@ -389,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}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fitvete-food-cli",
-  "version": "1.4.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",