soustack 0.1.2 → 0.2.1

package/README.md

@@ -35,10 +35,10 @@ Soustack is **computational**—it understands _how_ a recipe behaves.
 npm install soustack
 ```
 
-## What’s Included
+## What's Included
 
 - **Validation**: `validateRecipe()` validates Soustack JSON against the bundled schema.
-- **Scaling & Computation**: `scaleRecipe()` produces a flat, UI-ready “computed recipe” (scaled ingredients + aggregated timing).
+- **Scaling & Computation**: `scaleRecipe()` produces a flat, UI-ready "computed recipe" (scaled ingredients + aggregated timing).
 - **Parsers**:
   - Ingredient parsing (`parseIngredient`, `parseIngredientLine`)
   - Duration parsing (`smartParseDuration`)
@@ -46,9 +46,15 @@ npm install soustack
 - **Schema.org Conversion**:
   - `fromSchemaOrg()` (Schema.org JSON-LD → Soustack)
   - `toSchemaOrg()` (Soustack → Schema.org JSON-LD)
-- **Web Scraping**:
+  - `normalizeImage()` utility for converting Schema.org image formats to Soustack format
+- **Image Support**:
+  - Recipe-level images: single URL or array of URLs
+  - Instruction-level images: optional image URL per step
+  - Automatic normalization from Schema.org ImageObject formats
+- **Web Scraping**: 
   - `scrapeRecipe()` fetches a recipe page and extracts Schema.org recipe data (Node.js only)
-  - `extractRecipeFromHTML()` extracts recipe data from HTML string (browser & Node.js compatible)
+  - `extractRecipeFromHTML()` extracts recipe data from HTML string, returns Soustack format (browser & Node.js compatible)
+  - `extractSchemaOrgRecipeFromHTML()` extracts raw Schema.org recipe data from HTML string (browser & Node.js compatible)
   - Supports JSON-LD (`<script type="application/ld+json">`) and Microdata (`itemscope/itemtype`)
 
 ## Programmatic Usage
@@ -57,10 +63,12 @@ npm install soustack
 import {
   scrapeRecipe,
   extractRecipeFromHTML,
+  extractSchemaOrgRecipeFromHTML,
   fromSchemaOrg,
   toSchemaOrg,
   validateRecipe,
   scaleRecipe,
+  normalizeImage,
 } from 'soustack';
 
 // Validate a Soustack recipe JSON object
@@ -73,25 +81,67 @@ const computed = scaleRecipe(recipe, 2);
 const scraped = await scrapeRecipe('https://example.com/recipe');
 
 // Extract recipe from HTML string (browser & Node.js compatible)
+// Option 1: Get Soustack format directly
 const html = await fetch('https://example.com/recipe').then((r) => r.text());
 const recipe = extractRecipeFromHTML(html);
 
+// Option 2: Get Schema.org format first (for inspection/modification)
+const schemaOrgRecipe = extractSchemaOrgRecipeFromHTML(html);
+if (schemaOrgRecipe) {
+  const soustackRecipe = fromSchemaOrg(schemaOrgRecipe);
+}
+
 // Convert Schema.org → Soustack
 const soustack = fromSchemaOrg(schemaOrgJsonLd);
 
 // Convert Soustack → Schema.org
 const jsonLd = toSchemaOrg(recipe);
+
+// Normalize Schema.org image formats (strings, arrays, ImageObjects)
+const normalized = normalizeImage(schemaOrgRecipe.image);
+// Returns: string | string[] | undefined
 ```
 
 ## 🔁 Schema.org Conversion
 
-Use the new helpers to move between Schema.org JSON-LD and Soustack's structured recipe format.
+Use the helpers to move between Schema.org JSON-LD and Soustack's structured recipe format. The conversion automatically handles image normalization, supporting multiple image formats from Schema.org.
 
 ```ts
-import { fromSchemaOrg, toSchemaOrg } from 'soustack';
+import { fromSchemaOrg, toSchemaOrg, normalizeImage } from 'soustack';
 
+// Convert Schema.org → Soustack (automatically normalizes images)
 const soustackRecipe = fromSchemaOrg(schemaOrgJsonLd);
+// Recipe images: string | string[] | undefined
+// Instruction images: optional image URL per step
+
+// Convert Soustack → Schema.org (preserves images)
 const schemaOrgRecipe = toSchemaOrg(soustackRecipe);
+
+// Manual image normalization (if needed)
+const normalized = normalizeImage(schemaOrgImage);
+// Handles: strings, arrays, ImageObjects with url/contentUrl
+```
+
+### Image Format Support
+
+Soustack supports flexible image formats:
+
+- **Recipe-level images**: Single URL (`string`) or multiple URLs (`string[]`)
+- **Instruction-level images**: Optional `image` property on instruction objects
+- **Automatic normalization**: Schema.org ImageObjects are automatically converted to URLs during import
+
+Example recipe with images:
+
+```ts
+const recipe = {
+  name: "Chocolate Cake",
+  image: ["https://example.com/hero.jpg", "https://example.com/gallery.jpg"],
+  instructions: [
+    "Mix dry ingredients",
+    { text: "Decorate the cake", image: "https://example.com/decorate.jpg" },
+    "Serve"
+  ]
+};
 ```
 
 ## 🧰 Web Scraping
@@ -115,9 +165,11 @@ const recipe = await scrapeRecipe('https://example.com/recipe', {
 });
 ```
 
-### Browser: `extractRecipeFromHTML()`
+### Browser: `extractRecipeFromHTML()` and `extractSchemaOrgRecipeFromHTML()`
+
+#### `extractRecipeFromHTML()` - Returns Soustack Format
 
-`extractRecipeFromHTML(html)` extracts recipe data from an HTML string. **Works in both browser and Node.js**. Perfect for browser usage where you fetch HTML yourself (with cookies/session for authenticated content).
+`extractRecipeFromHTML(html)` extracts recipe data from an HTML string and returns it in Soustack format. **Works in both browser and Node.js**. Perfect for browser usage where you fetch HTML yourself (with cookies/session for authenticated content).
 
 ```ts
 import { extractRecipeFromHTML } from 'soustack';
@@ -125,15 +177,39 @@ import { extractRecipeFromHTML } from 'soustack';
 // In browser: fetch HTML yourself (bypasses CORS, uses your cookies/session)
 const response = await fetch('https://example.com/recipe');
 const html = await response.text();
-const recipe = extractRecipeFromHTML(html);
+const recipe = extractRecipeFromHTML(html); // Already in Soustack format
+```
+
+#### `extractSchemaOrgRecipeFromHTML()` - Returns Schema.org Format
+
+`extractSchemaOrgRecipeFromHTML(html)` extracts the raw Schema.org recipe data from HTML. Returns `null` if no recipe is found. Use this when you need to inspect, debug, or modify the Schema.org data before converting to Soustack format.
+
+```ts
+import { extractSchemaOrgRecipeFromHTML, fromSchemaOrg } from 'soustack';
+
+// In browser: fetch HTML yourself
+const response = await fetch('https://example.com/recipe');
+const html = await response.text();
+
+// Extract Schema.org format (for inspection/modification)
+const schemaOrgRecipe = extractSchemaOrgRecipeFromHTML(html);
+
+if (schemaOrgRecipe) {
+  // Inspect or modify Schema.org data before converting
+  console.log('Found recipe:', schemaOrgRecipe.name);
+  
+  // Convert to Soustack format when ready
+  const soustackRecipe = fromSchemaOrg(schemaOrgRecipe);
+}
 ```
 
-**Why use `extractRecipeFromHTML()` in browsers?**
+**Why use these functions in browsers?**
 
 - ✅ No CORS issues — you fetch HTML yourself
 - ✅ Works with authenticated/paywalled content — uses browser cookies
 - ✅ Smaller bundle — no Node.js dependencies
 - ✅ Universal — works in both browser and Node.js environments
+- ✅ Flexible — choose Schema.org format for inspection/modification, or Soustack format for direct use
 
 ### CLI
 

package/dist/cli/index.js

@@ -163,8 +163,8 @@ function flattenInstructions(items) {
 // src/schema.json
 var schema_default = {
   $schema: "http://json-schema.org/draft-07/schema#",
-  $id: "http://soustack.org/schema/v0.1",
-  title: "Soustack Recipe Schema v0.1",
+  $id: "http://soustack.org/schema/v0.2",
+  title: "Soustack Recipe Schema v0.2",
   description: "A portable, scalable, interoperable recipe format.",
   type: "object",
   required: ["name", "ingredients", "instructions"],
@@ -194,8 +194,21 @@ var schema_default = {
       items: { type: "string" }
     },
     image: {
-      type: "string",
-      format: "uri"
+      description: "Recipe-level hero image(s)",
+      anyOf: [
+        {
+          type: "string",
+          format: "uri"
+        },
+        {
+          type: "array",
+          minItems: 1,
+          items: {
+            type: "string",
+            format: "uri"
+          }
+        }
+      ]
     },
     dateAdded: {
       type: "string",
@@ -360,6 +373,11 @@ var schema_default = {
       properties: {
         id: { type: "string" },
         text: { type: "string" },
+        image: {
+          type: "string",
+          format: "uri",
+          description: "Optional image that illustrates this instruction"
+        },
         destination: { type: "string" },
         dependsOn: {
           type: "array",
@@ -1250,6 +1268,40 @@ function smartParseDuration(input) {
   return parseHumanDuration(input);
 }
 
+// src/utils/image.ts
+function normalizeImage(image) {
+  if (!image) {
+    return void 0;
+  }
+  if (typeof image === "string") {
+    const trimmed = image.trim();
+    return trimmed || void 0;
+  }
+  if (Array.isArray(image)) {
+    const urls = image.map((entry) => typeof entry === "string" ? entry.trim() : extractUrl(entry)).filter((url) => typeof url === "string" && Boolean(url));
+    if (urls.length === 0) {
+      return void 0;
+    }
+    if (urls.length === 1) {
+      return urls[0];
+    }
+    return urls;
+  }
+  return extractUrl(image);
+}
+function extractUrl(value) {
+  if (!value || typeof value !== "object") {
+    return void 0;
+  }
+  const record = value;
+  const candidate = typeof record.url === "string" ? record.url : typeof record.contentUrl === "string" ? record.contentUrl : void 0;
+  if (!candidate) {
+    return void 0;
+  }
+  const trimmed = candidate.trim();
+  return trimmed || void 0;
+}
+
 // src/fromSchemaOrg.ts
 function fromSchemaOrg(input) {
   const recipeNode = extractRecipeNode(input);
@@ -1262,13 +1314,12 @@ function fromSchemaOrg(input) {
   const recipeYield = parseYield(recipeNode.recipeYield);
   const tags = collectTags(recipeNode.recipeCuisine, recipeNode.keywords);
   const category = extractFirst(recipeNode.recipeCategory);
-  const image = convertImage(recipeNode.image);
   const source = convertSource(recipeNode);
   const nutrition = recipeNode.nutrition && typeof recipeNode.nutrition === "object" ? recipeNode.nutrition : void 0;
   return {
     name: recipeNode.name.trim(),
     description: recipeNode.description?.trim() || void 0,
-    image,
+    image: normalizeImage(recipeNode.image),
     category,
     tags: tags.length ? tags : void 0,
     source,
@@ -1351,9 +1402,9 @@ function convertInstructions(value) {
       continue;
     }
     if (isHowToStep(entry)) {
-      const text = extractInstructionText(entry);
-      if (text) {
-        result.push(text);
+      const parsed = convertHowToStep(entry);
+      if (parsed) {
+        result.push(parsed);
       }
     }
   }
@@ -1371,9 +1422,9 @@ function extractSectionItems(items = []) {
       continue;
     }
     if (isHowToStep(item)) {
-      const text = extractInstructionText(item);
-      if (text) {
-        result.push(text);
+      const parsed = convertHowToStep(item);
+      if (parsed) {
+        result.push(parsed);
       }
       continue;
     }
@@ -1387,6 +1438,17 @@ function extractInstructionText(value) {
   const text = typeof value.text === "string" ? value.text : value.name;
   return typeof text === "string" ? text.trim() || void 0 : void 0;
 }
+function convertHowToStep(step) {
+  const text = extractInstructionText(step);
+  if (!text) {
+    return void 0;
+  }
+  const normalizedImage = normalizeImage(step.image);
+  if (typeof normalizedImage === "string") {
+    return { text, image: normalizedImage };
+  }
+  return text;
+}
 function isHowToStep(value) {
   return Boolean(value) && typeof value === "object" && value["@type"] === "HowToStep";
 }
@@ -1428,26 +1490,6 @@ function extractFirst(value) {
   const arr = flattenStrings(value);
   return arr.length ? arr[0] : void 0;
 }
-function convertImage(value) {
-  if (!value) return void 0;
-  if (typeof value === "string") {
-    return value;
-  }
-  if (Array.isArray(value)) {
-    for (const item of value) {
-      const url = typeof item === "string" ? item : extractImageUrl(item);
-      if (url) return url;
-    }
-    return void 0;
-  }
-  return extractImageUrl(value);
-}
-function extractImageUrl(value) {
-  if (!value || typeof value !== "object") return void 0;
-  const record = value;
-  const candidate = typeof record.url === "string" ? record.url : typeof record.contentUrl === "string" ? record.contentUrl : void 0;
-  return candidate?.trim() || void 0;
-}
 function convertSource(recipe) {
   const author = extractEntityName(recipe.author);
   const publisher = extractEntityName(recipe.publisher);
@@ -1543,7 +1585,7 @@ function convertInstruction(entry) {
     return createHowToStep(entry);
   }
   if ("subsection" in entry) {
-    const steps = entry.items.map((item) => typeof item === "string" ? createHowToStep(item) : createHowToStep(item.text)).filter((step) => Boolean(step));
+    const steps = entry.items.map((item) => createHowToStep(item)).filter((step) => Boolean(step));
     if (!steps.length) {
       return null;
     }
@@ -1554,18 +1596,34 @@ function convertInstruction(entry) {
     };
   }
   if ("text" in entry) {
-    return createHowToStep(entry.text);
+    return createHowToStep(entry);
   }
   return createHowToStep(String(entry));
 }
-function createHowToStep(text) {
-  if (!text) return null;
-  const trimmed = text.trim();
-  if (!trimmed) return null;
-  return {
+function createHowToStep(entry) {
+  if (!entry) return null;
+  if (typeof entry === "string") {
+    const trimmed2 = entry.trim();
+    if (!trimmed2) {
+      return null;
+    }
+    return {
+      "@type": "HowToStep",
+      text: trimmed2
+    };
+  }
+  const trimmed = entry.text?.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const step = {
     "@type": "HowToStep",
     text: trimmed
   };
+  if (entry.image) {
+    step.image = entry.image;
+  }
+  return step;
 }
 function convertTime2(time) {
   if (!time) {
@@ -1728,7 +1786,7 @@ async function fetchPage(url, options = {}) {
       };
       const response = await resolvedFetch(url, requestInit);
       clearTimeout(timeoutId);
-      if (response && (typeof process === "undefined" || process.env.NODE_ENV !== "test")) {
+      if (response && typeof process !== "undefined" && process.env.NODE_ENV !== "test") {
         try {
           const globalFetch = typeof globalThis !== "undefined" && typeof globalThis.fetch !== "undefined" ? globalThis.fetch : null;
           if (globalFetch) {
@@ -1746,7 +1804,7 @@ async function fetchPage(url, options = {}) {
         throw error;
       }
       const html = await response.text();
-      if (typeof process === "undefined" || process.env.NODE_ENV !== "test") {
+      if (typeof process !== "undefined" && process.env.NODE_ENV !== "test") {
         try {
           const globalFetch = typeof globalThis !== "undefined" && typeof globalThis.fetch !== "undefined" ? globalThis.fetch : null;
           if (globalFetch) {
@@ -2006,14 +2064,30 @@ function extractRecipe(html) {
     return extractRecipeBrowser(html);
   }
   const jsonLdRecipe = extractJsonLd(html);
-  fetch("http://127.0.0.1:7243/ingest/7225c3b5-9ac2-4c94-b561-807ca9003b66", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ location: "scraper/extractors/index.ts:6", message: "JSON-LD extraction result", data: { hasJsonLd: !!jsonLdRecipe }, timestamp: Date.now(), sessionId: "debug-session", runId: "run1", hypothesisId: "C,D" }) }).catch(() => {
-  });
+  if (typeof process !== "undefined" && process.env.NODE_ENV !== "test") {
+    try {
+      const globalFetch = typeof globalThis !== "undefined" && typeof globalThis.fetch !== "undefined" ? globalThis.fetch : null;
+      if (globalFetch) {
+        globalFetch("http://127.0.0.1:7243/ingest/7225c3b5-9ac2-4c94-b561-807ca9003b66", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ location: "scraper/extractors/index.ts:6", message: "JSON-LD extraction result", data: { hasJsonLd: !!jsonLdRecipe }, timestamp: Date.now(), sessionId: "debug-session", runId: "run1", hypothesisId: "C,D" }) }).catch(() => {
+        });
+      }
+    } catch {
+    }
+  }
   if (jsonLdRecipe) {
     return { recipe: jsonLdRecipe, source: "jsonld" };
   }
   const microdataRecipe = extractMicrodata(html);
-  fetch("http://127.0.0.1:7243/ingest/7225c3b5-9ac2-4c94-b561-807ca9003b66", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ location: "scraper/extractors/index.ts:12", message: "Microdata extraction result", data: { hasMicrodata: !!microdataRecipe }, timestamp: Date.now(), sessionId: "debug-session", runId: "run1", hypothesisId: "D" }) }).catch(() => {
-  });
+  if (typeof process !== "undefined" && process.env.NODE_ENV !== "test") {
+    try {
+      const globalFetch = typeof globalThis !== "undefined" && typeof globalThis.fetch !== "undefined" ? globalThis.fetch : null;
+      if (globalFetch) {
+        globalFetch("http://127.0.0.1:7243/ingest/7225c3b5-9ac2-4c94-b561-807ca9003b66", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ location: "scraper/extractors/index.ts:12", message: "Microdata extraction result", data: { hasMicrodata: !!microdataRecipe }, timestamp: Date.now(), sessionId: "debug-session", runId: "run1", hypothesisId: "D" }) }).catch(() => {
+        });
+      }
+    } catch {
+    }
+  }
   if (microdataRecipe) {
     return { recipe: microdataRecipe, source: "microdata" };
   }
@@ -2022,20 +2096,52 @@ function extractRecipe(html) {
 
 // src/scraper/index.ts
 async function scrapeRecipe(url, options = {}) {
-  fetch("http://127.0.0.1:7243/ingest/7225c3b5-9ac2-4c94-b561-807ca9003b66", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ location: "scraper/index.ts:7", message: "scrapeRecipe entry", data: { url, hasOptions: !!options }, timestamp: Date.now(), sessionId: "debug-session", runId: "run1", hypothesisId: "A,B,C,D,E" }) }).catch(() => {
-  });
+  if (typeof process !== "undefined" && process.env.NODE_ENV !== "test") {
+    try {
+      const globalFetch = typeof globalThis !== "undefined" && typeof globalThis.fetch !== "undefined" ? globalThis.fetch : null;
+      if (globalFetch) {
+        globalFetch("http://127.0.0.1:7243/ingest/7225c3b5-9ac2-4c94-b561-807ca9003b66", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ location: "scraper/index.ts:7", message: "scrapeRecipe entry", data: { url, hasOptions: !!options }, timestamp: Date.now(), sessionId: "debug-session", runId: "run1", hypothesisId: "A,B,C,D,E" }) }).catch(() => {
+        });
+      }
+    } catch {
+    }
+  }
   const html = await fetchPage(url, options);
-  fetch("http://127.0.0.1:7243/ingest/7225c3b5-9ac2-4c94-b561-807ca9003b66", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ location: "scraper/index.ts:9", message: "HTML fetched", data: { htmlLength: html?.length, htmlPreview: html?.substring(0, 200) }, timestamp: Date.now(), sessionId: "debug-session", runId: "run1", hypothesisId: "B" }) }).catch(() => {
-  });
+  if (typeof process !== "undefined" && process.env.NODE_ENV !== "test") {
+    try {
+      const globalFetch = typeof globalThis !== "undefined" && typeof globalThis.fetch !== "undefined" ? globalThis.fetch : null;
+      if (globalFetch) {
+        globalFetch("http://127.0.0.1:7243/ingest/7225c3b5-9ac2-4c94-b561-807ca9003b66", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ location: "scraper/index.ts:9", message: "HTML fetched", data: { htmlLength: html?.length, htmlPreview: html?.substring(0, 200) }, timestamp: Date.now(), sessionId: "debug-session", runId: "run1", hypothesisId: "B" }) }).catch(() => {
+        });
+      }
+    } catch {
+    }
+  }
   const { recipe } = extractRecipe(html);
-  fetch("http://127.0.0.1:7243/ingest/7225c3b5-9ac2-4c94-b561-807ca9003b66", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ location: "scraper/index.ts:11", message: "extractRecipe result", data: { hasRecipe: !!recipe, recipeType: recipe?.["@type"], recipeName: recipe?.name }, timestamp: Date.now(), sessionId: "debug-session", runId: "run1", hypothesisId: "A,C,D" }) }).catch(() => {
-  });
+  if (typeof process !== "undefined" && process.env.NODE_ENV !== "test") {
+    try {
+      const globalFetch = typeof globalThis !== "undefined" && typeof globalThis.fetch !== "undefined" ? globalThis.fetch : null;
+      if (globalFetch) {
+        globalFetch("http://127.0.0.1:7243/ingest/7225c3b5-9ac2-4c94-b561-807ca9003b66", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ location: "scraper/index.ts:11", message: "extractRecipe result", data: { hasRecipe: !!recipe, recipeType: recipe?.["@type"], recipeName: recipe?.name }, timestamp: Date.now(), sessionId: "debug-session", runId: "run1", hypothesisId: "A,C,D" }) }).catch(() => {
+        });
+      }
+    } catch {
+    }
+  }
   if (!recipe) {
     throw new Error("No Schema.org recipe data found in page");
   }
   const soustackRecipe = fromSchemaOrg(recipe);
-  fetch("http://127.0.0.1:7243/ingest/7225c3b5-9ac2-4c94-b561-807ca9003b66", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ location: "scraper/index.ts:17", message: "fromSchemaOrg result", data: { hasSoustackRecipe: !!soustackRecipe, soustackRecipeName: soustackRecipe?.name }, timestamp: Date.now(), sessionId: "debug-session", runId: "run1", hypothesisId: "A" }) }).catch(() => {
-  });
+  if (typeof process !== "undefined" && process.env.NODE_ENV !== "test") {
+    try {
+      const globalFetch = typeof globalThis !== "undefined" && typeof globalThis.fetch !== "undefined" ? globalThis.fetch : null;
+      if (globalFetch) {
+        globalFetch("http://127.0.0.1:7243/ingest/7225c3b5-9ac2-4c94-b561-807ca9003b66", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ location: "scraper/index.ts:17", message: "fromSchemaOrg result", data: { hasSoustackRecipe: !!soustackRecipe, soustackRecipeName: soustackRecipe?.name }, timestamp: Date.now(), sessionId: "debug-session", runId: "run1", hypothesisId: "A" }) }).catch(() => {
+        });
+      }
+    } catch {
+    }
+  }
   if (!soustackRecipe) {
     throw new Error("Schema.org data did not include a valid recipe");
   }