soustack 0.1.2 → 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";
@@ -245,7 +249,7 @@ declare function validateRecipe(data: any): data is Recipe;
 
 declare function fromSchemaOrg(input: unknown): Recipe | null;
 
-interface SchemaOrgRecipe {
+interface SchemaOrgRecipe$1 {
     '@context'?: string;
     '@type'?: string | string[];
     name: string;
@@ -270,11 +274,14 @@ interface SchemaOrgRecipe {
     '@graph'?: unknown;
 }
 type SchemaOrgIngredientList = string | string[];
-type SchemaOrgInstructionList = string | HowToStep | HowToSection | Array<string | HowToStep | HowToSection>;
+type SchemaOrgInstructionList = string | HowToStep$1 | HowToSection | Array<string | HowToStep$1 | HowToSection>;
 interface SchemaOrgImageObject {
     '@type'?: string;
     url?: string;
     contentUrl?: string;
+    width?: number;
+    height?: number;
+    [key: string]: unknown;
 }
 type SchemaOrgImage = string | SchemaOrgImageObject | Array<string | SchemaOrgImageObject>;
 interface SchemaOrgYield {
@@ -282,17 +289,17 @@ interface SchemaOrgYield {
     unit?: string;
     description?: string;
 }
-interface HowToStep {
+interface HowToStep$1 {
     '@type': 'HowToStep';
     text?: string;
     name?: string;
     url?: string;
-    image?: string;
+    image?: SchemaOrgImage;
 }
 interface HowToSection {
     '@type': 'HowToSection';
     name: string;
-    itemListElement: Array<string | HowToStep | HowToSection>;
+    itemListElement: Array<string | HowToStep$1 | HowToSection>;
 }
 interface SchemaOrgPersonOrOrganization {
     '@type'?: 'Person' | 'Organization';
@@ -303,8 +310,30 @@ interface NutritionInformation {
     [key: string]: string | number | null | undefined;
 }
 
-declare function toSchemaOrg(recipe: Recipe): SchemaOrgRecipe;
+declare function toSchemaOrg(recipe: Recipe): SchemaOrgRecipe$1;
 
+interface HowToStep {
+    '@type'?: 'HowToStep' | 'HowToSection' | string;
+    name?: string;
+    text?: string;
+    itemListElement?: Array<string | HowToStep>;
+}
+interface SchemaOrgRecipe {
+    '@type': string | string[];
+    name?: string;
+    description?: string;
+    image?: string | string[];
+    recipeIngredient?: string[];
+    recipeInstructions?: Array<string | HowToStep>;
+    recipeYield?: string | number;
+    prepTime?: string;
+    cookTime?: string;
+    totalTime?: string;
+    author?: unknown;
+    datePublished?: string;
+    aggregateRating?: unknown;
+    [key: string]: unknown;
+}
 interface FetchRequestInit {
     headers?: Record<string, string>;
     signal?: AbortSignal;
@@ -357,6 +386,33 @@ declare function scrapeRecipe(url: string, options?: ScrapeRecipeOptions): Promi
  * @throws Error if no recipe is found
  */
 declare function extractRecipeFromHTML(html: string): Recipe;
+/**
+ * Extract Schema.org recipe data from HTML string (browser-compatible).
+ *
+ * Returns the raw Schema.org recipe object, which can then be converted
+ * to Soustack format using fromSchemaOrg(). This gives you access to the
+ * original Schema.org data for inspection, debugging, or custom transformations.
+ *
+ * @param html - HTML string containing Schema.org recipe data
+ * @returns Schema.org recipe object, or null if not found
+ *
+ * @example
+ * ```ts
+ * // In browser:
+ * const response = await fetch('https://example.com/recipe');
+ * const html = await response.text();
+ * const schemaOrgRecipe = extractSchemaOrgRecipeFromHTML(html);
+ *
+ * if (schemaOrgRecipe) {
+ *   // Inspect or modify Schema.org data before converting
+ *   console.log('Found recipe:', schemaOrgRecipe.name);
+ *
+ *   // Convert to Soustack format
+ *   const soustackRecipe = fromSchemaOrg(schemaOrgRecipe);
+ * }
+ * ```
+ */
+declare function extractSchemaOrgRecipeFromHTML(html: string): SchemaOrgRecipe | null;
 
 declare function normalizeIngredientInput(input: string): string;
 declare function parseIngredient(text: string): ParsedIngredient;
@@ -376,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 SimpleTime, type Source, type StepTiming, type Storage, type StorageMethod, type StructuredTime, type Substitution, type Time, type Yield, extractRecipeFromHTML, 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";
@@ -245,7 +249,7 @@ declare function validateRecipe(data: any): data is Recipe;
 
 declare function fromSchemaOrg(input: unknown): Recipe | null;
 
-interface SchemaOrgRecipe {
+interface SchemaOrgRecipe$1 {
     '@context'?: string;
     '@type'?: string | string[];
     name: string;
@@ -270,11 +274,14 @@ interface SchemaOrgRecipe {
     '@graph'?: unknown;
 }
 type SchemaOrgIngredientList = string | string[];
-type SchemaOrgInstructionList = string | HowToStep | HowToSection | Array<string | HowToStep | HowToSection>;
+type SchemaOrgInstructionList = string | HowToStep$1 | HowToSection | Array<string | HowToStep$1 | HowToSection>;
 interface SchemaOrgImageObject {
     '@type'?: string;
     url?: string;
     contentUrl?: string;
+    width?: number;
+    height?: number;
+    [key: string]: unknown;
 }
 type SchemaOrgImage = string | SchemaOrgImageObject | Array<string | SchemaOrgImageObject>;
 interface SchemaOrgYield {
@@ -282,17 +289,17 @@ interface SchemaOrgYield {
     unit?: string;
     description?: string;
 }
-interface HowToStep {
+interface HowToStep$1 {
     '@type': 'HowToStep';
     text?: string;
     name?: string;
     url?: string;
-    image?: string;
+    image?: SchemaOrgImage;
 }
 interface HowToSection {
     '@type': 'HowToSection';
     name: string;
-    itemListElement: Array<string | HowToStep | HowToSection>;
+    itemListElement: Array<string | HowToStep$1 | HowToSection>;
 }
 interface SchemaOrgPersonOrOrganization {
     '@type'?: 'Person' | 'Organization';
@@ -303,8 +310,30 @@ interface NutritionInformation {
     [key: string]: string | number | null | undefined;
 }
 
-declare function toSchemaOrg(recipe: Recipe): SchemaOrgRecipe;
+declare function toSchemaOrg(recipe: Recipe): SchemaOrgRecipe$1;
 
+interface HowToStep {
+    '@type'?: 'HowToStep' | 'HowToSection' | string;
+    name?: string;
+    text?: string;
+    itemListElement?: Array<string | HowToStep>;
+}
+interface SchemaOrgRecipe {
+    '@type': string | string[];
+    name?: string;
+    description?: string;
+    image?: string | string[];
+    recipeIngredient?: string[];
+    recipeInstructions?: Array<string | HowToStep>;
+    recipeYield?: string | number;
+    prepTime?: string;
+    cookTime?: string;
+    totalTime?: string;
+    author?: unknown;
+    datePublished?: string;
+    aggregateRating?: unknown;
+    [key: string]: unknown;
+}
 interface FetchRequestInit {
     headers?: Record<string, string>;
     signal?: AbortSignal;
@@ -357,6 +386,33 @@ declare function scrapeRecipe(url: string, options?: ScrapeRecipeOptions): Promi
  * @throws Error if no recipe is found
  */
 declare function extractRecipeFromHTML(html: string): Recipe;
+/**
+ * Extract Schema.org recipe data from HTML string (browser-compatible).
+ *
+ * Returns the raw Schema.org recipe object, which can then be converted
+ * to Soustack format using fromSchemaOrg(). This gives you access to the
+ * original Schema.org data for inspection, debugging, or custom transformations.
+ *
+ * @param html - HTML string containing Schema.org recipe data
+ * @returns Schema.org recipe object, or null if not found
+ *
+ * @example
+ * ```ts
+ * // In browser:
+ * const response = await fetch('https://example.com/recipe');
+ * const html = await response.text();
+ * const schemaOrgRecipe = extractSchemaOrgRecipeFromHTML(html);
+ *
+ * if (schemaOrgRecipe) {
+ *   // Inspect or modify Schema.org data before converting
+ *   console.log('Found recipe:', schemaOrgRecipe.name);
+ *
+ *   // Convert to Soustack format
+ *   const soustackRecipe = fromSchemaOrg(schemaOrgRecipe);
+ * }
+ * ```
+ */
+declare function extractSchemaOrgRecipeFromHTML(html: string): SchemaOrgRecipe | null;
 
 declare function normalizeIngredientInput(input: string): string;
 declare function parseIngredient(text: string): ParsedIngredient;
@@ -376,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 SimpleTime, type Source, type StepTiming, type Storage, type StorageMethod, type StructuredTime, type Substitution, type Time, type Yield, extractRecipeFromHTML, 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 };