soustack 0.1.3 → 0.2.3

package/dist/index.d.mts

@@ -1,21 +1,27 @@
 /**
- * Soustack Recipe Schema v0.1
+ * Soustack Recipe Schema v0.2.1
  * A portable, scalable, interoperable recipe format.
  */
-interface Recipe {
+interface SoustackRecipe {
+    /** Optional $schema pointer for profile-aware validation */
+    $schema?: string;
     /** Unique identifier (slug or UUID) */
     id?: string;
+    /** Optional display title */
+    title?: string;
     /** The title of the recipe */
     name: string;
     /** Semantic versioning (e.g., 1.0.0) */
+    recipeVersion?: string;
+    /** Deprecated alias for recipeVersion */
     version?: string;
     description?: string;
     /** Primary category (e.g., "Main Course") */
     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 */
@@ -29,7 +35,10 @@ interface Recipe {
     storage?: Storage;
     substitutions?: Substitution[];
     nutrition?: NutritionFacts;
+    metadata?: Record<string, unknown>;
+    [k: `x-${string}`]: unknown;
 }
+type Recipe = SoustackRecipe;
 interface Source {
     author?: string;
     url?: string;
@@ -147,7 +156,7 @@ interface InstructionSubsection {
     subsection: string;
     items: (string | Instruction)[];
 }
-interface Instruction {
+interface SoustackInstruction {
     id?: string;
     text: string;
     destination?: string;
@@ -156,9 +165,12 @@ 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;
+    duration: number | string;
     type: "active" | "passive";
     scaling?: "linear" | "fixed" | "sqrt";
 }
@@ -207,46 +219,43 @@ interface NutritionFacts {
     [key: string]: string | number | null | string[] | undefined;
 }
 
-/**
- * A "Computed Recipe" is the result of running the parser.
- * It is flat, strict, and ready for the UI to render.
- */
-interface ComputedRecipe {
-    metadata: {
-        targetYield: number;
-        baseYield: number;
-        multiplier: number;
-    };
-    ingredients: ComputedIngredient[];
-    instructions: ComputedInstruction[];
-    timing: {
-        active: number;
-        passive: number;
-        total: number;
+interface ScaleRecipeOptions {
+    multiplier?: number;
+    targetYield?: {
+        amount: number;
+        unit?: string;
     };
 }
-interface ComputedIngredient {
-    id: string;
-    name: string;
-    amount: number;
-    unit: string | null;
-    text: string;
-    notes?: string;
-}
-interface ComputedInstruction {
-    id: string;
-    text: string;
-    durationMinutes: number;
-    type: 'active' | 'passive';
-}
-declare function scaleRecipe(recipe: Recipe, targetYieldAmount: number): ComputedRecipe;
+declare function scaleRecipe(recipe: Recipe, options?: ScaleRecipeOptions): Recipe;
 
-declare function validateRecipe(data: any): data is Recipe;
+type ProfileName = "base" | "cookable" | "scalable" | "quantified" | "illustrated" | "schedulable";
+interface NormalizedError {
+    path: string;
+    message: string;
+    keyword?: string;
+}
+interface NormalizedWarning {
+    path: string;
+    message: string;
+}
+interface ValidateOptions {
+    profile?: ProfileName;
+    schema?: string;
+    collectAllErrors?: boolean;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: NormalizedError[];
+    warnings: NormalizedWarning[];
+    normalized?: Recipe;
+}
+declare function validateRecipe(input: any, options?: ValidateOptions): ValidationResult;
+declare function detectProfiles(recipe: any): ProfileName[];
 
 declare function fromSchemaOrg(input: unknown): Recipe | null;
 
 interface SchemaOrgRecipe$1 {
-    '@context'?: string;
+    '@context'?: string | Array<string | Record<string, unknown>> | Record<string, unknown>;
     '@type'?: string | string[];
     name: string;
     description?: string;
@@ -275,6 +284,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 +299,13 @@ interface HowToStep$1 {
     text?: string;
     name?: string;
     url?: string;
-    image?: string;
+    image?: SchemaOrgImage;
+    '@id'?: string;
+    id?: string;
+    totalTime?: string;
+    performTime?: string;
+    prepTime?: string;
+    duration?: string;
 }
 interface HowToSection {
     '@type': 'HowToSection';
@@ -327,102 +345,9 @@ interface SchemaOrgRecipe {
     aggregateRating?: unknown;
     [key: string]: unknown;
 }
-interface FetchRequestInit {
-    headers?: Record<string, string>;
-    signal?: AbortSignal;
-    redirect?: 'follow' | 'error' | 'manual';
-}
-interface FetchResponse {
-    ok: boolean;
-    status: number;
-    statusText: string;
-    text(): Promise<string>;
-}
-type FetchImplementation = (url: string, init?: FetchRequestInit) => Promise<FetchResponse>;
-interface FetchOptions {
-    timeout?: number;
-    userAgent?: string;
-    maxRetries?: number;
-    fetchFn?: FetchImplementation;
-}
-interface ScrapeRecipeOptions extends FetchOptions {
-}
 
-/**
- * Scrapes a recipe from a URL (Node.js only).
- *
- * ⚠️ Not available in browser environments due to CORS restrictions.
- * For browser usage, fetch the HTML yourself and use extractRecipeFromHTML().
- *
- * @param url - The URL of the recipe page to scrape
- * @param options - Fetch options (timeout, userAgent, maxRetries)
- * @returns A Soustack recipe object
- * @throws Error if no recipe is found
- */
-declare function scrapeRecipe(url: string, options?: ScrapeRecipeOptions): Promise<Recipe>;
-/**
- * Extracts a recipe from HTML string (browser and Node.js compatible).
- *
- * This function works in both environments and doesn't require network access.
- * Perfect for browser usage where you fetch HTML yourself (with cookies/session).
- *
- * @example
- * ```ts
- * // In browser:
- * const response = await fetch('https://example.com/recipe');
- * const html = await response.text();
- * const recipe = extractRecipeFromHTML(html);
- * ```
- *
- * @param html - The HTML string containing Schema.org recipe data
- * @returns A Soustack recipe object
- * @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;
-declare function parseIngredientLine(text: string): ParsedIngredient;
-declare function parseIngredients(texts: string[]): ParsedIngredient[];
-
-declare function parseDuration(iso: string): number | null;
-declare function parseDuration(iso: string | null | undefined): number | null;
-declare function formatDuration(minutes: number): string;
-declare function formatDuration(minutes: number | null | undefined): string;
-declare function parseHumanDuration(text: string): number | null;
-declare function parseHumanDuration(text: string | null | undefined): number | null;
-declare function smartParseDuration(input: string): number | null;
-declare function smartParseDuration(input: string | null | undefined): number | null;
-
-declare function normalizeYield(text: string): string;
-declare function parseYield(text: string): ParsedYield | null;
-declare function formatYield(value: ParsedYield): string;
+declare const SOUSTACK_SPEC_VERSION = "0.2.1";
 
-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 };
+export { type Alternative, 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, SOUSTACK_SPEC_VERSION, type Scaling, type ScalingBakersPercentage, type ScalingBase, type ScalingDiscrete, type ScalingFixed, type ScalingLinear, type ScalingProportional, type SimpleTime, type Source, type SoustackInstruction, type SoustackRecipe, type StepTiming, type Storage, type StorageMethod, type StructuredTime, type Substitution, type Time, type Yield, detectProfiles, extractSchemaOrgRecipeFromHTML, fromSchemaOrg, scaleRecipe, toSchemaOrg, validateRecipe };

package/dist/index.d.ts

@@ -1,21 +1,27 @@
 /**
- * Soustack Recipe Schema v0.1
+ * Soustack Recipe Schema v0.2.1
  * A portable, scalable, interoperable recipe format.
  */
-interface Recipe {
+interface SoustackRecipe {
+    /** Optional $schema pointer for profile-aware validation */
+    $schema?: string;
     /** Unique identifier (slug or UUID) */
     id?: string;
+    /** Optional display title */
+    title?: string;
     /** The title of the recipe */
     name: string;
     /** Semantic versioning (e.g., 1.0.0) */
+    recipeVersion?: string;
+    /** Deprecated alias for recipeVersion */
     version?: string;
     description?: string;
     /** Primary category (e.g., "Main Course") */
     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 */
@@ -29,7 +35,10 @@ interface Recipe {
     storage?: Storage;
     substitutions?: Substitution[];
     nutrition?: NutritionFacts;
+    metadata?: Record<string, unknown>;
+    [k: `x-${string}`]: unknown;
 }
+type Recipe = SoustackRecipe;
 interface Source {
     author?: string;
     url?: string;
@@ -147,7 +156,7 @@ interface InstructionSubsection {
     subsection: string;
     items: (string | Instruction)[];
 }
-interface Instruction {
+interface SoustackInstruction {
     id?: string;
     text: string;
     destination?: string;
@@ -156,9 +165,12 @@ 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;
+    duration: number | string;
     type: "active" | "passive";
     scaling?: "linear" | "fixed" | "sqrt";
 }
@@ -207,46 +219,43 @@ interface NutritionFacts {
     [key: string]: string | number | null | string[] | undefined;
 }
 
-/**
- * A "Computed Recipe" is the result of running the parser.
- * It is flat, strict, and ready for the UI to render.
- */
-interface ComputedRecipe {
-    metadata: {
-        targetYield: number;
-        baseYield: number;
-        multiplier: number;
-    };
-    ingredients: ComputedIngredient[];
-    instructions: ComputedInstruction[];
-    timing: {
-        active: number;
-        passive: number;
-        total: number;
+interface ScaleRecipeOptions {
+    multiplier?: number;
+    targetYield?: {
+        amount: number;
+        unit?: string;
     };
 }
-interface ComputedIngredient {
-    id: string;
-    name: string;
-    amount: number;
-    unit: string | null;
-    text: string;
-    notes?: string;
-}
-interface ComputedInstruction {
-    id: string;
-    text: string;
-    durationMinutes: number;
-    type: 'active' | 'passive';
-}
-declare function scaleRecipe(recipe: Recipe, targetYieldAmount: number): ComputedRecipe;
+declare function scaleRecipe(recipe: Recipe, options?: ScaleRecipeOptions): Recipe;
 
-declare function validateRecipe(data: any): data is Recipe;
+type ProfileName = "base" | "cookable" | "scalable" | "quantified" | "illustrated" | "schedulable";
+interface NormalizedError {
+    path: string;
+    message: string;
+    keyword?: string;
+}
+interface NormalizedWarning {
+    path: string;
+    message: string;
+}
+interface ValidateOptions {
+    profile?: ProfileName;
+    schema?: string;
+    collectAllErrors?: boolean;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: NormalizedError[];
+    warnings: NormalizedWarning[];
+    normalized?: Recipe;
+}
+declare function validateRecipe(input: any, options?: ValidateOptions): ValidationResult;
+declare function detectProfiles(recipe: any): ProfileName[];
 
 declare function fromSchemaOrg(input: unknown): Recipe | null;
 
 interface SchemaOrgRecipe$1 {
-    '@context'?: string;
+    '@context'?: string | Array<string | Record<string, unknown>> | Record<string, unknown>;
     '@type'?: string | string[];
     name: string;
     description?: string;
@@ -275,6 +284,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 +299,13 @@ interface HowToStep$1 {
     text?: string;
     name?: string;
     url?: string;
-    image?: string;
+    image?: SchemaOrgImage;
+    '@id'?: string;
+    id?: string;
+    totalTime?: string;
+    performTime?: string;
+    prepTime?: string;
+    duration?: string;
 }
 interface HowToSection {
     '@type': 'HowToSection';
@@ -327,102 +345,9 @@ interface SchemaOrgRecipe {
     aggregateRating?: unknown;
     [key: string]: unknown;
 }
-interface FetchRequestInit {
-    headers?: Record<string, string>;
-    signal?: AbortSignal;
-    redirect?: 'follow' | 'error' | 'manual';
-}
-interface FetchResponse {
-    ok: boolean;
-    status: number;
-    statusText: string;
-    text(): Promise<string>;
-}
-type FetchImplementation = (url: string, init?: FetchRequestInit) => Promise<FetchResponse>;
-interface FetchOptions {
-    timeout?: number;
-    userAgent?: string;
-    maxRetries?: number;
-    fetchFn?: FetchImplementation;
-}
-interface ScrapeRecipeOptions extends FetchOptions {
-}
 
-/**
- * Scrapes a recipe from a URL (Node.js only).
- *
- * ⚠️ Not available in browser environments due to CORS restrictions.
- * For browser usage, fetch the HTML yourself and use extractRecipeFromHTML().
- *
- * @param url - The URL of the recipe page to scrape
- * @param options - Fetch options (timeout, userAgent, maxRetries)
- * @returns A Soustack recipe object
- * @throws Error if no recipe is found
- */
-declare function scrapeRecipe(url: string, options?: ScrapeRecipeOptions): Promise<Recipe>;
-/**
- * Extracts a recipe from HTML string (browser and Node.js compatible).
- *
- * This function works in both environments and doesn't require network access.
- * Perfect for browser usage where you fetch HTML yourself (with cookies/session).
- *
- * @example
- * ```ts
- * // In browser:
- * const response = await fetch('https://example.com/recipe');
- * const html = await response.text();
- * const recipe = extractRecipeFromHTML(html);
- * ```
- *
- * @param html - The HTML string containing Schema.org recipe data
- * @returns A Soustack recipe object
- * @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;
-declare function parseIngredientLine(text: string): ParsedIngredient;
-declare function parseIngredients(texts: string[]): ParsedIngredient[];
-
-declare function parseDuration(iso: string): number | null;
-declare function parseDuration(iso: string | null | undefined): number | null;
-declare function formatDuration(minutes: number): string;
-declare function formatDuration(minutes: number | null | undefined): string;
-declare function parseHumanDuration(text: string): number | null;
-declare function parseHumanDuration(text: string | null | undefined): number | null;
-declare function smartParseDuration(input: string): number | null;
-declare function smartParseDuration(input: string | null | undefined): number | null;
-
-declare function normalizeYield(text: string): string;
-declare function parseYield(text: string): ParsedYield | null;
-declare function formatYield(value: ParsedYield): string;
+declare const SOUSTACK_SPEC_VERSION = "0.2.1";
 
-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 };
+export { type Alternative, 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, SOUSTACK_SPEC_VERSION, type Scaling, type ScalingBakersPercentage, type ScalingBase, type ScalingDiscrete, type ScalingFixed, type ScalingLinear, type ScalingProportional, type SimpleTime, type Source, type SoustackInstruction, type SoustackRecipe, type StepTiming, type Storage, type StorageMethod, type StructuredTime, type Substitution, type Time, type Yield, detectProfiles, extractSchemaOrgRecipeFromHTML, fromSchemaOrg, scaleRecipe, toSchemaOrg, validateRecipe };