soustack 0.2.3 → 0.4.0

package/dist/index.d.mts

@@ -1,10 +1,26 @@
 /**
- * Soustack Recipe Schema v0.2.1
+ * Soustack Recipe Schema v0.3.0
  * A portable, scalable, interoperable recipe format.
  */
 interface SoustackRecipe {
+    /** Document marker for Soustack recipes */
+    '@type'?: 'Recipe';
     /** Optional $schema pointer for profile-aware validation */
     $schema?: string;
+    /** Optional declared validation profile */
+    profile?: string;
+    /** Recipe level: "lite" or "base" */
+    level?: "lite" | "base";
+    /** Stack declarations as a map: Record<stackName, versionNumber> */
+    stacks?: Record<string, number>;
+    /** Attribution stack payload */
+    attribution?: AttributionModule;
+    /** Taxonomy stack payload */
+    taxonomy?: TaxonomyModule;
+    /** Media stack payload */
+    media?: MediaModule;
+    /** Times stack payload */
+    times?: TimesModule;
     /** Unique identifier (slug or UUID) */
     id?: string;
     /** Optional display title */
@@ -77,25 +93,25 @@ interface Equipment {
     name: string;
     required?: boolean;
     label?: string;
-    capacity?: Quantity;
+    capacity?: Quantity$1;
     scalingLimit?: number;
     alternatives?: string[];
 }
-interface Quantity {
+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 IngredientItem = string | Ingredient | IngredientSubsection;
+type IngredientItem = string | Ingredient$1 | IngredientSubsection;
 interface IngredientSubsection {
     subsection: string;
-    items: (string | Ingredient)[];
+    items: (string | Ingredient$1)[];
 }
-interface Ingredient {
+interface Ingredient$1 {
     id?: string;
     /** Full human-readable text (e.g. "2 cups flour") */
     item: string;
-    quantity?: Quantity;
+    quantity?: Quantity$1;
     name?: string;
     aisle?: string;
     /** Required prep state (e.g. "diced") */
@@ -208,15 +224,27 @@ interface Alternative {
     dietary?: string[];
 }
 interface NutritionFacts {
-    calories?: string;
-    fatContent?: string;
-    carbohydrateContent?: string;
-    proteinContent?: string;
-    fiberContent?: string;
-    sugarContent?: string;
-    sodiumContent?: string;
-    servingSize?: string;
-    [key: string]: string | number | null | string[] | undefined;
+    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 ScaleRecipeOptions {
@@ -228,32 +256,76 @@ interface ScaleRecipeOptions {
 }
 declare function scaleRecipe(recipe: Recipe, options?: ScaleRecipeOptions): Recipe;
 
-type ProfileName = "base" | "cookable" | "scalable" | "quantified" | "illustrated" | "schedulable";
-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" | "minimal" | "core";
+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[];
@@ -276,6 +348,7 @@ interface SchemaOrgRecipe$1 {
     datePublished?: string;
     dateModified?: string;
     nutrition?: NutritionInformation;
+    video?: SchemaOrgImage;
     '@graph'?: unknown;
 }
 type SchemaOrgIngredientList = string | string[];
@@ -321,6 +394,14 @@ interface NutritionInformation {
     [key: string]: string | number | null | undefined;
 }
 
+/**
+ * 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 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;
 
 interface HowToStep {
@@ -348,6 +429,69 @@ interface SchemaOrgRecipe {
 
 declare function extractSchemaOrgRecipeFromHTML(html: string): SchemaOrgRecipe | null;
 
-declare const SOUSTACK_SPEC_VERSION = "0.2.1";
+declare const SOUSTACK_SPEC_VERSION = "0.3.0";
+
+type ConvertTarget = 'metric';
+type ConvertMode = 'volume' | 'mass';
+type RoundMode = 'none' | 'sane';
+interface LineItem {
+    ingredient: string;
+    quantity: number;
+    unit: string | null;
+}
+interface ConvertedLineItem extends LineItem {
+    notes?: string;
+}
+declare class UnknownUnitError extends Error {
+    readonly unit: string;
+    constructor(unit: string);
+}
+declare class UnsupportedConversionError extends Error {
+    readonly unit: string;
+    readonly mode: ConvertMode;
+    constructor(unit: string, mode: ConvertMode);
+}
+declare class MissingEquivalencyError extends Error {
+    readonly ingredient: string;
+    readonly unit: string;
+    constructor(ingredient: string, unit: string);
+}
+declare function convertLineItemToMetric(item: LineItem, mode: ConvertMode, opts?: {
+    round?: RoundMode;
+}): ConvertedLineItem;
+
+interface Quantity {
+    amount: number;
+    unit?: string | null;
+}
+interface Ingredient {
+    id?: string;
+    item: string;
+    quantity?: Quantity;
+    name?: string;
+    prep?: string;
+    prepAction?: string;
+    prepActions?: string[];
+    form?: string;
+    prepTime?: number;
+    optional?: boolean;
+    notes?: string;
+}
+interface MiseEnPlaceTask {
+    category: 'prep' | 'state' | 'measure' | 'other';
+    action?: string;
+    form?: string;
+    items: Array<{
+        ingredient: string;
+        quantity?: Quantity;
+        optional?: boolean;
+        notes?: string;
+    }>;
+}
+interface MiseEnPlacePlan {
+    tasks: MiseEnPlaceTask[];
+    ungrouped: Ingredient[];
+}
+declare function miseEnPlace(ingredients: Ingredient[]): MiseEnPlacePlan;
 
-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 };
+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 NormalizationResult, 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 ValidateMode, type ValidateResult, type Yield, convertLineItemToMetric, detectProfiles, extractSchemaOrgRecipeFromHTML, fromSchemaOrg, miseEnPlace, normalizeRecipe, scaleRecipe, toSchemaOrg, validateRecipe };

package/dist/index.d.ts

@@ -1,10 +1,26 @@
 /**
- * Soustack Recipe Schema v0.2.1
+ * Soustack Recipe Schema v0.3.0
  * A portable, scalable, interoperable recipe format.
  */
 interface SoustackRecipe {
+    /** Document marker for Soustack recipes */
+    '@type'?: 'Recipe';
     /** Optional $schema pointer for profile-aware validation */
     $schema?: string;
+    /** Optional declared validation profile */
+    profile?: string;
+    /** Recipe level: "lite" or "base" */
+    level?: "lite" | "base";
+    /** Stack declarations as a map: Record<stackName, versionNumber> */
+    stacks?: Record<string, number>;
+    /** Attribution stack payload */
+    attribution?: AttributionModule;
+    /** Taxonomy stack payload */
+    taxonomy?: TaxonomyModule;
+    /** Media stack payload */
+    media?: MediaModule;
+    /** Times stack payload */
+    times?: TimesModule;
     /** Unique identifier (slug or UUID) */
     id?: string;
     /** Optional display title */
@@ -77,25 +93,25 @@ interface Equipment {
     name: string;
     required?: boolean;
     label?: string;
-    capacity?: Quantity;
+    capacity?: Quantity$1;
     scalingLimit?: number;
     alternatives?: string[];
 }
-interface Quantity {
+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 IngredientItem = string | Ingredient | IngredientSubsection;
+type IngredientItem = string | Ingredient$1 | IngredientSubsection;
 interface IngredientSubsection {
     subsection: string;
-    items: (string | Ingredient)[];
+    items: (string | Ingredient$1)[];
 }
-interface Ingredient {
+interface Ingredient$1 {
     id?: string;
     /** Full human-readable text (e.g. "2 cups flour") */
     item: string;
-    quantity?: Quantity;
+    quantity?: Quantity$1;
     name?: string;
     aisle?: string;
     /** Required prep state (e.g. "diced") */
@@ -208,15 +224,27 @@ interface Alternative {
     dietary?: string[];
 }
 interface NutritionFacts {
-    calories?: string;
-    fatContent?: string;
-    carbohydrateContent?: string;
-    proteinContent?: string;
-    fiberContent?: string;
-    sugarContent?: string;
-    sodiumContent?: string;
-    servingSize?: string;
-    [key: string]: string | number | null | string[] | undefined;
+    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 ScaleRecipeOptions {
@@ -228,32 +256,76 @@ interface ScaleRecipeOptions {
 }
 declare function scaleRecipe(recipe: Recipe, options?: ScaleRecipeOptions): Recipe;
 
-type ProfileName = "base" | "cookable" | "scalable" | "quantified" | "illustrated" | "schedulable";
-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" | "minimal" | "core";
+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[];
@@ -276,6 +348,7 @@ interface SchemaOrgRecipe$1 {
     datePublished?: string;
     dateModified?: string;
     nutrition?: NutritionInformation;
+    video?: SchemaOrgImage;
     '@graph'?: unknown;
 }
 type SchemaOrgIngredientList = string | string[];
@@ -321,6 +394,14 @@ interface NutritionInformation {
     [key: string]: string | number | null | undefined;
 }
 
+/**
+ * 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 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;
 
 interface HowToStep {
@@ -348,6 +429,69 @@ interface SchemaOrgRecipe {
 
 declare function extractSchemaOrgRecipeFromHTML(html: string): SchemaOrgRecipe | null;
 
-declare const SOUSTACK_SPEC_VERSION = "0.2.1";
+declare const SOUSTACK_SPEC_VERSION = "0.3.0";
+
+type ConvertTarget = 'metric';
+type ConvertMode = 'volume' | 'mass';
+type RoundMode = 'none' | 'sane';
+interface LineItem {
+    ingredient: string;
+    quantity: number;
+    unit: string | null;
+}
+interface ConvertedLineItem extends LineItem {
+    notes?: string;
+}
+declare class UnknownUnitError extends Error {
+    readonly unit: string;
+    constructor(unit: string);
+}
+declare class UnsupportedConversionError extends Error {
+    readonly unit: string;
+    readonly mode: ConvertMode;
+    constructor(unit: string, mode: ConvertMode);
+}
+declare class MissingEquivalencyError extends Error {
+    readonly ingredient: string;
+    readonly unit: string;
+    constructor(ingredient: string, unit: string);
+}
+declare function convertLineItemToMetric(item: LineItem, mode: ConvertMode, opts?: {
+    round?: RoundMode;
+}): ConvertedLineItem;
+
+interface Quantity {
+    amount: number;
+    unit?: string | null;
+}
+interface Ingredient {
+    id?: string;
+    item: string;
+    quantity?: Quantity;
+    name?: string;
+    prep?: string;
+    prepAction?: string;
+    prepActions?: string[];
+    form?: string;
+    prepTime?: number;
+    optional?: boolean;
+    notes?: string;
+}
+interface MiseEnPlaceTask {
+    category: 'prep' | 'state' | 'measure' | 'other';
+    action?: string;
+    form?: string;
+    items: Array<{
+        ingredient: string;
+        quantity?: Quantity;
+        optional?: boolean;
+        notes?: string;
+    }>;
+}
+interface MiseEnPlacePlan {
+    tasks: MiseEnPlaceTask[];
+    ungrouped: Ingredient[];
+}
+declare function miseEnPlace(ingredients: Ingredient[]): MiseEnPlacePlan;
 
-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 };
+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 NormalizationResult, 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 ValidateMode, type ValidateResult, type Yield, convertLineItemToMetric, detectProfiles, extractSchemaOrgRecipeFromHTML, fromSchemaOrg, miseEnPlace, normalizeRecipe, scaleRecipe, toSchemaOrg, validateRecipe };