soustack 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Soustack Recipe Schema v0.3.0
+ * Soustack Recipe Schema v0.0.2
  * A portable, scalable, interoperable recipe format.
  */
 interface SoustackRecipe {
@@ -7,18 +7,10 @@ interface SoustackRecipe {
     '@type'?: 'Recipe';
     /** Optional $schema pointer for profile-aware validation */
     $schema?: string;
-    /** Optional declared validation profile */
-    profile?: string;
-    /** Enabled module identifiers (e.g., "nutrition@1") */
-    modules?: string[];
-    /** Attribution module payload */
-    attribution?: AttributionModule;
-    /** Taxonomy module payload */
-    taxonomy?: TaxonomyModule;
-    /** Media module payload */
-    media?: MediaModule;
-    /** Times module payload */
-    times?: TimesModule;
+    /** Optional declared validation profile (vNext only) */
+    profile?: "base" | "equipped" | "illustrated" | "lite" | "prepped" | "scalable" | "timed";
+    /** Stack declarations as a map: Record<stackName, versionNumber> */
+    stacks?: Record<string, number>;
     /** Unique identifier (slug or UUID) */
     id?: string;
     /** Optional display title */
@@ -35,6 +27,10 @@ interface SoustackRecipe {
     /** Additional tags for filtering */
     tags?: string[];
     /** URL(s) to recipe image(s) */
+    images?: string[];
+    /** URL(s) to recipe video(s) */
+    videos?: string[];
+    /** Legacy image field preserved for compatibility */
     image?: string | string[];
     /** ISO 8601 date string */
     dateAdded?: string;
@@ -72,19 +68,18 @@ interface ParsedYield {
     description?: string;
 }
 /**
- * Time can be structured (machine-readable) or simple (strings).
- * Structured time takes precedence if both exist.
+ * Time uses DurationMinutes format (vNext).
+ * Required total field with minutes.
  */
-type Time = StructuredTime | SimpleTime;
-interface StructuredTime {
-    prep?: number;
-    active?: number;
-    passive?: number;
-    total?: number;
-}
-interface SimpleTime {
-    prepTime?: string;
-    cookTime?: string;
+interface Time {
+    total: DurationMinutes;
+    metadata?: Record<string, unknown>;
+    [k: `x-${string}`]: unknown;
+}
+interface DurationMinutes {
+    minutes: number;
+    metadata?: Record<string, unknown>;
+    [k: `x-${string}`]: unknown;
 }
 interface Equipment {
     id?: string;
@@ -94,99 +89,144 @@ interface Equipment {
     capacity?: Quantity$1;
     scalingLimit?: number;
     alternatives?: string[];
+    count?: number;
+    countScaling?: EquipmentCountScaling;
+    upgrades?: EquipmentUpgradeRule[];
 }
 interface Quantity$1 {
     amount: number;
     /** Unit string (e.g. "g", "cup") or null for count-based items (e.g. "2 eggs") */
     unit: string | null;
 }
+type EquipmentCountScaling = 'fixed' | 'linear' | EquipmentThresholdScaling;
+interface EquipmentThresholdScaling {
+    mode: 'threshold';
+    steps: EquipmentThresholdStep[];
+}
+interface EquipmentThresholdStep {
+    maxFactor: number;
+    count: number;
+}
+interface EquipmentUpgradeRule {
+    minFactor: number;
+    use: string;
+}
+interface EquipmentUpgradeRecommendation {
+    fromId: string;
+    use: string;
+    minFactor: number;
+}
+interface ScalingMetadata {
+    multiplier: number;
+    equipment?: {
+        upgrades: EquipmentUpgradeRecommendation[];
+    };
+}
+type ScaledRecipe = Recipe & {
+    scaling?: ScalingMetadata;
+};
 type IngredientItem = string | Ingredient$1 | IngredientSubsection;
 interface IngredientSubsection {
-    subsection: string;
-    items: (string | Ingredient$1)[];
+    section: string;
+    ingredients: IngredientItem[];
 }
 interface Ingredient$1 {
     id?: string;
-    /** Full human-readable text (e.g. "2 cups flour") */
-    item: string;
+    /** Ingredient name (required in vNext) */
+    name: string;
     quantity?: Quantity$1;
-    name?: string;
-    aisle?: string;
-    /** Required prep state (e.g. "diced") */
-    prep?: string;
-    prepAction?: string;
-    prepTime?: number;
+    /** Required prep state (e.g. "diced") or array of prep items */
+    prep?: string | string[];
     /** ID of equipment where this ingredient goes */
     destination?: string;
     scaling?: Scaling;
-    critical?: boolean;
     optional?: boolean;
     notes?: string;
+    temperature?: Temperature;
+    metadata?: Record<string, unknown>;
+    [k: `x-${string}`]: unknown;
 }
 interface ParsedIngredient {
-    item: string;
+    name: string;
     quantity?: {
         amount: number | null;
         unit: string | null;
     };
-    name?: string;
     prep?: string;
     optional?: boolean;
     notes?: string;
     scaling?: Scaling;
 }
 /**
- * Intelligent Scaling Logic
+ * Intelligent Scaling Logic (vNext format)
  * Defines how an ingredient behaves when the recipe yield changes.
  */
-type Scaling = ScalingLinear | ScalingDiscrete | ScalingProportional | ScalingFixed | ScalingBakersPercentage;
+type Scaling = ScalingLinear | ScalingDiscrete | ScalingProportional | ScalingFixed | ScalingToTaste | ScalingBakersPercentage;
 interface ScalingBase {
     min?: number;
     max?: number;
 }
 interface ScalingLinear extends ScalingBase {
-    type: "linear";
+    mode: "linear";
 }
 interface ScalingDiscrete extends ScalingBase {
-    type: "discrete";
-    roundTo?: number;
+    mode: "discrete";
+    step?: number;
+    rounding?: "nearest" | "ceil" | "floor";
 }
 interface ScalingProportional extends ScalingBase {
-    type: "proportional";
+    mode: "proportional";
     factor?: number;
 }
 interface ScalingFixed extends ScalingBase {
-    type: "fixed";
+    mode: "fixed";
+}
+interface ScalingToTaste {
+    mode: "toTaste";
 }
-interface ScalingBakersPercentage extends ScalingBase {
-    type: 'bakers_percentage';
+interface ScalingBakersPercentage {
+    mode: "bakersPercent";
+    /** The percentage relative to the reference (e.g. 2 for 2%) */
+    percent: number;
     /** The ID of the flour/base ingredient this is relative to */
-    referenceId: string;
-    /** The percentage relative to the reference (e.g. 0.02 for 2%) */
-    factor?: number;
+    of: string;
 }
 type InstructionItem = string | Instruction | InstructionSubsection;
 interface InstructionSubsection {
-    subsection: string;
-    items: (string | Instruction)[];
+    section: string;
+    steps: InstructionItem[];
 }
 interface SoustackInstruction {
     id?: string;
     text: string;
-    destination?: string;
     /** IDs of steps that must complete before this one starts */
     dependsOn?: string[];
     /** IDs of ingredients used in this step */
     inputs?: string[];
+    /** IDs of techniques used in this step */
+    techniqueIds?: string[];
+    /** IDs of equipment used in this step */
+    usesEquipment?: string[];
     timing?: StepTiming;
-    /** Optional image URL for this instruction */
-    image?: string;
+    temperature?: Temperature;
+    images?: string[];
+    videos?: string[];
+    metadata?: Record<string, unknown>;
+    [k: `x-${string}`]: unknown;
 }
 type Instruction = SoustackInstruction;
 interface StepTiming {
-    duration: number | string;
-    type: "active" | "passive";
-    scaling?: "linear" | "fixed" | "sqrt";
+    activity: "active" | "passive";
+    duration?: DurationMinutes | DurationRange;
+    completionCue?: string;
+    metadata?: Record<string, unknown>;
+    [k: `x-${string}`]: unknown;
+}
+interface DurationRange {
+    minMinutes: number;
+    maxMinutes: number;
+    metadata?: Record<string, unknown>;
+    [k: `x-${string}`]: unknown;
 }
 interface Storage {
     roomTemp?: StorageMethod;
@@ -225,24 +265,11 @@ interface NutritionFacts {
     calories?: number;
     protein_g?: number;
 }
-interface AttributionModule {
-    url?: string;
-    author?: string;
-    datePublished?: string;
-}
-interface TaxonomyModule {
-    keywords?: string[];
-    category?: string;
-    cuisine?: string;
-}
-interface MediaModule {
-    images?: string[];
-    videos?: string[];
-}
-interface TimesModule {
-    prepMinutes?: number;
-    cookMinutes?: number;
-    totalMinutes?: number;
+interface Temperature {
+    value: number;
+    unit: "celsius" | "fahrenheit";
+    metadata?: Record<string, unknown>;
+    [k: `x-${string}`]: unknown;
 }
 
 interface ScaleRecipeOptions {
@@ -254,32 +281,76 @@ interface ScaleRecipeOptions {
 }
 declare function scaleRecipe(recipe: Recipe, options?: ScaleRecipeOptions): Recipe;
 
-type ProfileName = "minimal" | "core";
-interface NormalizedError {
+type ConformanceSeverity = "error" | "warning";
+interface ConformanceIssue {
+    code: string;
     path: string;
     message: string;
-    keyword?: string;
+    severity: ConformanceSeverity;
 }
-interface NormalizedWarning {
+
+type ProfileName = "base" | "equipped" | "illustrated" | "lite" | "prepped" | "scalable" | "timed";
+interface NormalizedError {
     path: string;
     message: string;
+    keyword?: string;
 }
+/**
+ * Validation modes for recipe validation.
+ * - "schema": JSON Schema only
+ * - "full": JSON Schema + semantic conformance checks
+ */
+type ValidateMode = "schema" | "full";
 interface ValidateOptions {
     profile?: ProfileName;
     schema?: string;
     collectAllErrors?: boolean;
+    mode?: ValidateMode;
+    includeNormalized?: boolean;
 }
-interface ValidationResult {
-    valid: boolean;
-    errors: NormalizedError[];
-    warnings: NormalizedWarning[];
-    normalized?: Recipe;
+/**
+ * Result payload for recipe validation. Schema validation always runs first;
+ * conformance issues are only included when running in full mode.
+ */
+interface ValidateResult {
+    ok: boolean;
+    schemaErrors: NormalizedError[];
+    conformanceIssues: ConformanceIssue[];
+    warnings: string[];
+    normalizedRecipe?: Recipe;
 }
-declare function validateRecipe(input: any, options?: ValidateOptions): ValidationResult;
+/**
+ * Legacy validateRecipe function - now uses the new validateRecipeSchema internally
+ * but maintains backward compatibility with profile/stack-based validation
+ * Also includes semantic conformance validation.
+ */
+/**
+ * Validates a recipe with explicit validation modes.
+ * - mode="schema": JSON Schema only
+ * - mode="full": schema + semantic conformance (only if schema passes)
+ */
+declare function validateRecipe(input: any, options?: ValidateOptions): ValidateResult;
 declare function detectProfiles(recipe: any): ProfileName[];
 
 declare function fromSchemaOrg(input: unknown): Recipe | null;
 
+interface NormalizationResult {
+    recipe: Recipe;
+    warnings: string[];
+}
+/**
+ * Normalizes a recipe input to the current spec format:
+ * - Rejects inputs with legacy field (unsupported)
+ * - Converts legacy `stacks` array format to map format
+ * - Ensures `stacks` exists even if empty
+ * - Preserves existing `stacks` map format
+ *
+ * @param input - Raw recipe input (may have legacy formats)
+ * @returns Normalized recipe with warnings for any issues encountered
+ * @throws Error if input contains legacy field
+ */
+declare function normalizeRecipe(input: unknown): NormalizationResult;
+
 interface SchemaOrgRecipe$1 {
     '@context'?: string | Array<string | Record<string, unknown>> | Record<string, unknown>;
     '@type'?: string | string[];
@@ -304,6 +375,7 @@ interface SchemaOrgRecipe$1 {
     nutrition?: NutritionInformation;
     video?: SchemaOrgImage;
     '@graph'?: unknown;
+    $schema?: string;
 }
 type SchemaOrgIngredientList = string | string[];
 type SchemaOrgInstructionList = string | HowToStep$1 | HowToSection | Array<string | HowToStep$1 | HowToSection>;
@@ -351,9 +423,9 @@ interface NutritionInformation {
 /**
  * Convert a Soustack recipe to Schema.org JSON-LD format.
  *
- * BREAKING CHANGE in v0.3.0: This function now targets the "minimal" profile
- * and only includes modules that are schemaOrgMappable (as defined in the
- * modules registry). Non-mappable modules (e.g., nutrition@1, schedule@1)
+ * BREAKING CHANGE in v0.0.2: This function now targets the "minimal" profile
+ * and only includes stacks that are schemaOrgMappable (as defined in the
+ * stacks registry). Non-mappable stacks (e.g., nutrition@1, schedule@1)
  * are excluded from the conversion.
  */
 declare function toSchemaOrg(recipe: Recipe): SchemaOrgRecipe$1;
@@ -383,7 +455,7 @@ interface SchemaOrgRecipe {
 
 declare function extractSchemaOrgRecipeFromHTML(html: string): SchemaOrgRecipe | null;
 
-declare const SOUSTACK_SPEC_VERSION = "0.3.0";
+declare const SOUSTACK_SPEC_VERSION = "0.0.2";
 
 type ConvertTarget = 'metric';
 type ConvertMode = 'volume' | 'mass';
@@ -448,4 +520,4 @@ interface MiseEnPlacePlan {
 }
 declare function miseEnPlace(ingredients: Ingredient[]): MiseEnPlacePlan;
 
-export { type Alternative, type AttributionModule, type ConvertMode, type ConvertTarget, type ConvertedLineItem, type Equipment, type FrozenStorageMethod, type Ingredient$1 as Ingredient, type IngredientItem, type IngredientSubsection, type Instruction, type InstructionItem, type InstructionSubsection, type LineItem, type MakeAheadComponent, type MediaModule, type Ingredient as MiseEnPlaceIngredient, type MiseEnPlacePlan, type Quantity as MiseEnPlaceQuantity, type MiseEnPlaceTask, MissingEquivalencyError, type NutritionFacts, type ParsedIngredient, type ParsedYield, type Quantity$1 as Quantity, type Recipe, type RoundMode, 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 TaxonomyModule, type Time, type TimesModule, UnknownUnitError, UnsupportedConversionError, type Yield, convertLineItemToMetric, detectProfiles, extractSchemaOrgRecipeFromHTML, fromSchemaOrg, miseEnPlace, scaleRecipe, toSchemaOrg, validateRecipe };
+export { type Alternative, type ConvertMode, type ConvertTarget, type ConvertedLineItem, type DurationMinutes, type DurationRange, type Equipment, type EquipmentCountScaling, type EquipmentThresholdScaling, type EquipmentThresholdStep, type EquipmentUpgradeRecommendation, type EquipmentUpgradeRule, type FrozenStorageMethod, type Ingredient$1 as Ingredient, type IngredientItem, type IngredientSubsection, type Instruction, type InstructionItem, type InstructionSubsection, type LineItem, type MakeAheadComponent, type Ingredient as MiseEnPlaceIngredient, type MiseEnPlacePlan, type Quantity as MiseEnPlaceQuantity, type MiseEnPlaceTask, MissingEquivalencyError, type NormalizationResult, type NutritionFacts, type ParsedIngredient, type ParsedYield, type Quantity$1 as Quantity, type Recipe, type RoundMode, SOUSTACK_SPEC_VERSION, type ScaledRecipe, type Scaling, type ScalingBakersPercentage, type ScalingBase, type ScalingDiscrete, type ScalingFixed, type ScalingLinear, type ScalingMetadata, type ScalingProportional, type ScalingToTaste, type Source, type SoustackInstruction, type SoustackRecipe, type StepTiming, type Storage, type StorageMethod, type Substitution, type Temperature, type Time, UnknownUnitError, UnsupportedConversionError, type ValidateMode, type ValidateResult, type Yield, convertLineItemToMetric, detectProfiles, extractSchemaOrgRecipeFromHTML, fromSchemaOrg, miseEnPlace, normalizeRecipe, scaleRecipe, toSchemaOrg, validateRecipe };