soustack 0.1.3 → 0.2.1

package/dist/index.d.mts

@@ -2,7 +2,7 @@
  * Soustack Recipe Schema v0.1
  * A portable, scalable, interoperable recipe format.
  */
-interface Recipe {
+interface SoustackRecipe {
     /** Unique identifier (slug or UUID) */
     id?: string;
     /** The title of the recipe */
@@ -14,8 +14,8 @@ interface Recipe {
     category?: string;
     /** Additional tags for filtering */
     tags?: string[];
-    /** URL to recipe image */
-    image?: string;
+    /** URL(s) to recipe image(s) */
+    image?: string | string[];
     /** ISO 8601 date string */
     dateAdded?: string;
     /** Last updated timestamp */
@@ -30,6 +30,7 @@ interface Recipe {
     substitutions?: Substitution[];
     nutrition?: NutritionFacts;
 }
+type Recipe = SoustackRecipe;
 interface Source {
     author?: string;
     url?: string;
@@ -147,7 +148,7 @@ interface InstructionSubsection {
     subsection: string;
     items: (string | Instruction)[];
 }
-interface Instruction {
+interface SoustackInstruction {
     id?: string;
     text: string;
     destination?: string;
@@ -156,7 +157,10 @@ interface Instruction {
     /** IDs of ingredients used in this step */
     inputs?: string[];
     timing?: StepTiming;
+    /** Optional image URL for this instruction */
+    image?: string;
 }
+type Instruction = SoustackInstruction;
 interface StepTiming {
     duration: number;
     type: "active" | "passive";
@@ -275,6 +279,9 @@ interface SchemaOrgImageObject {
     '@type'?: string;
     url?: string;
     contentUrl?: string;
+    width?: number;
+    height?: number;
+    [key: string]: unknown;
 }
 type SchemaOrgImage = string | SchemaOrgImageObject | Array<string | SchemaOrgImageObject>;
 interface SchemaOrgYield {
@@ -287,7 +294,7 @@ interface HowToStep$1 {
     text?: string;
     name?: string;
     url?: string;
-    image?: string;
+    image?: SchemaOrgImage;
 }
 interface HowToSection {
     '@type': 'HowToSection';
@@ -425,4 +432,12 @@ declare function normalizeYield(text: string): string;
 declare function parseYield(text: string): ParsedYield | null;
 declare function formatYield(value: ParsedYield): string;
 
-export { type Alternative, type ComputedIngredient, type ComputedInstruction, type ComputedRecipe, type Equipment, type FrozenStorageMethod, type Ingredient, type IngredientItem, type IngredientSubsection, type Instruction, type InstructionItem, type InstructionSubsection, type MakeAheadComponent, type NutritionFacts, type ParsedIngredient, type ParsedYield, type Quantity, type Recipe, type Scaling, type ScalingBakersPercentage, type ScalingBase, type ScalingDiscrete, type ScalingFixed, type ScalingLinear, type ScalingProportional, type SchemaOrgRecipe, type SimpleTime, type Source, type StepTiming, type Storage, type StorageMethod, type StructuredTime, type Substitution, type Time, type Yield, extractRecipeFromHTML, extractSchemaOrgRecipeFromHTML, formatDuration, formatYield, fromSchemaOrg, normalizeIngredientInput, normalizeYield, parseDuration, parseHumanDuration, parseIngredient, parseIngredientLine, parseIngredients, parseYield, scaleRecipe, scrapeRecipe, smartParseDuration, toSchemaOrg, validateRecipe };
+/**
+ * Normalize Schema.org image formats to Soustack format.
+ * - String values pass through
+ * - Arrays collapse to string or string[] after URL extraction
+ * - ImageObjects extract their url/contentUrl
+ */
+declare function normalizeImage(image: SchemaOrgImage | undefined | null): string | string[] | undefined;
+
+export { type Alternative, type ComputedIngredient, type ComputedInstruction, type ComputedRecipe, type Equipment, type FrozenStorageMethod, type Ingredient, type IngredientItem, type IngredientSubsection, type Instruction, type InstructionItem, type InstructionSubsection, type MakeAheadComponent, type NutritionFacts, type ParsedIngredient, type ParsedYield, type Quantity, type Recipe, type Scaling, type ScalingBakersPercentage, type ScalingBase, type ScalingDiscrete, type ScalingFixed, type ScalingLinear, type ScalingProportional, type SchemaOrgRecipe, type SimpleTime, type Source, type SoustackInstruction, type SoustackRecipe, type StepTiming, type Storage, type StorageMethod, type StructuredTime, type Substitution, type Time, type Yield, extractRecipeFromHTML, extractSchemaOrgRecipeFromHTML, formatDuration, formatYield, fromSchemaOrg, normalizeImage, normalizeIngredientInput, normalizeYield, parseDuration, parseHumanDuration, parseIngredient, parseIngredientLine, parseIngredients, parseYield, scaleRecipe, scrapeRecipe, smartParseDuration, toSchemaOrg, validateRecipe };

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * Soustack Recipe Schema v0.1
  * A portable, scalable, interoperable recipe format.
  */
-interface Recipe {
+interface SoustackRecipe {
     /** Unique identifier (slug or UUID) */
     id?: string;
     /** The title of the recipe */
@@ -14,8 +14,8 @@ interface Recipe {
     category?: string;
     /** Additional tags for filtering */
     tags?: string[];
-    /** URL to recipe image */
-    image?: string;
+    /** URL(s) to recipe image(s) */
+    image?: string | string[];
     /** ISO 8601 date string */
     dateAdded?: string;
     /** Last updated timestamp */
@@ -30,6 +30,7 @@ interface Recipe {
     substitutions?: Substitution[];
     nutrition?: NutritionFacts;
 }
+type Recipe = SoustackRecipe;
 interface Source {
     author?: string;
     url?: string;
@@ -147,7 +148,7 @@ interface InstructionSubsection {
     subsection: string;
     items: (string | Instruction)[];
 }
-interface Instruction {
+interface SoustackInstruction {
     id?: string;
     text: string;
     destination?: string;
@@ -156,7 +157,10 @@ interface Instruction {
     /** IDs of ingredients used in this step */
     inputs?: string[];
     timing?: StepTiming;
+    /** Optional image URL for this instruction */
+    image?: string;
 }
+type Instruction = SoustackInstruction;
 interface StepTiming {
     duration: number;
     type: "active" | "passive";
@@ -275,6 +279,9 @@ interface SchemaOrgImageObject {
     '@type'?: string;
     url?: string;
     contentUrl?: string;
+    width?: number;
+    height?: number;
+    [key: string]: unknown;
 }
 type SchemaOrgImage = string | SchemaOrgImageObject | Array<string | SchemaOrgImageObject>;
 interface SchemaOrgYield {
@@ -287,7 +294,7 @@ interface HowToStep$1 {
     text?: string;
     name?: string;
     url?: string;
-    image?: string;
+    image?: SchemaOrgImage;
 }
 interface HowToSection {
     '@type': 'HowToSection';
@@ -425,4 +432,12 @@ declare function normalizeYield(text: string): string;
 declare function parseYield(text: string): ParsedYield | null;
 declare function formatYield(value: ParsedYield): string;
 
-export { type Alternative, type ComputedIngredient, type ComputedInstruction, type ComputedRecipe, type Equipment, type FrozenStorageMethod, type Ingredient, type IngredientItem, type IngredientSubsection, type Instruction, type InstructionItem, type InstructionSubsection, type MakeAheadComponent, type NutritionFacts, type ParsedIngredient, type ParsedYield, type Quantity, type Recipe, type Scaling, type ScalingBakersPercentage, type ScalingBase, type ScalingDiscrete, type ScalingFixed, type ScalingLinear, type ScalingProportional, type SchemaOrgRecipe, type SimpleTime, type Source, type StepTiming, type Storage, type StorageMethod, type StructuredTime, type Substitution, type Time, type Yield, extractRecipeFromHTML, extractSchemaOrgRecipeFromHTML, formatDuration, formatYield, fromSchemaOrg, normalizeIngredientInput, normalizeYield, parseDuration, parseHumanDuration, parseIngredient, parseIngredientLine, parseIngredients, parseYield, scaleRecipe, scrapeRecipe, smartParseDuration, toSchemaOrg, validateRecipe };
+/**
+ * Normalize Schema.org image formats to Soustack format.
+ * - String values pass through
+ * - Arrays collapse to string or string[] after URL extraction
+ * - ImageObjects extract their url/contentUrl
+ */
+declare function normalizeImage(image: SchemaOrgImage | undefined | null): string | string[] | undefined;
+
+export { type Alternative, type ComputedIngredient, type ComputedInstruction, type ComputedRecipe, type Equipment, type FrozenStorageMethod, type Ingredient, type IngredientItem, type IngredientSubsection, type Instruction, type InstructionItem, type InstructionSubsection, type MakeAheadComponent, type NutritionFacts, type ParsedIngredient, type ParsedYield, type Quantity, type Recipe, type Scaling, type ScalingBakersPercentage, type ScalingBase, type ScalingDiscrete, type ScalingFixed, type ScalingLinear, type ScalingProportional, type SchemaOrgRecipe, type SimpleTime, type Source, type SoustackInstruction, type SoustackRecipe, type StepTiming, type Storage, type StorageMethod, type StructuredTime, type Substitution, type Time, type Yield, extractRecipeFromHTML, extractSchemaOrgRecipeFromHTML, formatDuration, formatYield, fromSchemaOrg, normalizeImage, normalizeIngredientInput, normalizeYield, parseDuration, parseHumanDuration, parseIngredient, parseIngredientLine, parseIngredients, parseYield, scaleRecipe, scrapeRecipe, smartParseDuration, toSchemaOrg, validateRecipe };

package/dist/index.js

@@ -140,8 +140,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"],
@@ -171,8 +171,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",
@@ -337,6 +350,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",
@@ -1234,6 +1252,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);
@@ -1246,13 +1298,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,
@@ -1335,9 +1386,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);
       }
     }
   }
@@ -1355,9 +1406,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;
     }
@@ -1371,6 +1422,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";
 }
@@ -1412,26 +1474,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);
@@ -1527,7 +1569,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;
     }
@@ -1538,18 +1580,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) {
@@ -1712,7 +1770,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) {
@@ -1730,7 +1788,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) {
@@ -1990,7 +2048,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) {
@@ -2004,7 +2062,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) {
@@ -2022,7 +2080,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) {
@@ -2033,7 +2091,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) {
@@ -2044,7 +2102,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) {
@@ -2058,7 +2116,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) {
@@ -2336,6 +2394,7 @@ exports.extractSchemaOrgRecipeFromHTML = extractSchemaOrgRecipeFromHTML;
 exports.formatDuration = formatDuration;
 exports.formatYield = formatYield2;
 exports.fromSchemaOrg = fromSchemaOrg;
+exports.normalizeImage = normalizeImage;
 exports.normalizeIngredientInput = normalizeIngredientInput;
 exports.normalizeYield = normalizeYield;
 exports.parseDuration = parseDuration;