soustack 0.1.3 → 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,6 +46,11 @@ npm install soustack
 - **Schema.org Conversion**:
   - `fromSchemaOrg()` (Schema.org JSON-LD → Soustack)
   - `toSchemaOrg()` (Soustack → Schema.org JSON-LD)
+  - `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, returns Soustack format (browser & Node.js compatible)
@@ -63,6 +68,7 @@ import {
   toSchemaOrg,
   validateRecipe,
   scaleRecipe,
+  normalizeImage,
 } from 'soustack';
 
 // Validate a Soustack recipe JSON object
@@ -90,17 +96,52 @@ 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

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,7 +2064,7 @@ function extractRecipe(html) {
     return extractRecipeBrowser(html);
   }
   const jsonLdRecipe = extractJsonLd(html);
-  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) {
@@ -2020,7 +2078,7 @@ function extractRecipe(html) {
     return { recipe: jsonLdRecipe, source: "jsonld" };
   }
   const microdataRecipe = extractMicrodata(html);
-  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) {
@@ -2038,7 +2096,7 @@ function extractRecipe(html) {
 
 // src/scraper/index.ts
 async function scrapeRecipe(url, options = {}) {
-  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) {
@@ -2049,7 +2107,7 @@ async function scrapeRecipe(url, options = {}) {
     }
   }
   const html = await fetchPage(url, options);
-  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) {
@@ -2060,7 +2118,7 @@ async function scrapeRecipe(url, options = {}) {
     }
   }
   const { recipe } = extractRecipe(html);
-  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) {
@@ -2074,7 +2132,7 @@ async function scrapeRecipe(url, options = {}) {
     throw new Error("No Schema.org recipe data found in page");
   }
   const soustackRecipe = fromSchemaOrg(recipe);
-  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) {