soustack 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -1,13 +1,33 @@
 /**
- * Soustack Recipe Schema v0.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;
+    /** 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;
     /** 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") */
@@ -29,6 +49,8 @@ interface SoustackRecipe {
     storage?: Storage;
     substitutions?: Substitution[];
     nutrition?: NutritionFacts;
+    metadata?: Record<string, unknown>;
+    [k: `x-${string}`]: unknown;
 }
 type Recipe = SoustackRecipe;
 interface Source {
@@ -69,25 +91,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") */
@@ -162,7 +184,7 @@ interface SoustackInstruction {
 }
 type Instruction = SoustackInstruction;
 interface StepTiming {
-    duration: number;
+    duration: number | string;
     type: "active" | "passive";
     scaling?: "linear" | "fixed" | "sqrt";
 }
@@ -200,57 +222,66 @@ 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;
 }
-
-/**
- * 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 AttributionModule {
+    url?: string;
+    author?: string;
+    datePublished?: string;
 }
-interface ComputedIngredient {
-    id: string;
-    name: string;
-    amount: number;
-    unit: string | null;
-    text: string;
-    notes?: string;
+interface TaxonomyModule {
+    keywords?: string[];
+    category?: string;
+    cuisine?: string;
 }
-interface ComputedInstruction {
-    id: string;
-    text: string;
-    durationMinutes: number;
-    type: 'active' | 'passive';
+interface MediaModule {
+    images?: string[];
+    videos?: string[];
+}
+interface TimesModule {
+    prepMinutes?: number;
+    cookMinutes?: number;
+    totalMinutes?: number;
 }
-declare function scaleRecipe(recipe: Recipe, targetYieldAmount: number): ComputedRecipe;
 
-declare function validateRecipe(data: any): data is Recipe;
+interface ScaleRecipeOptions {
+    multiplier?: number;
+    targetYield?: {
+        amount: number;
+        unit?: string;
+    };
+}
+declare function scaleRecipe(recipe: Recipe, options?: ScaleRecipeOptions): Recipe;
+
+type ProfileName = "minimal" | "core";
+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;
@@ -271,6 +302,7 @@ interface SchemaOrgRecipe$1 {
     datePublished?: string;
     dateModified?: string;
     nutrition?: NutritionInformation;
+    video?: SchemaOrgImage;
     '@graph'?: unknown;
 }
 type SchemaOrgIngredientList = string | string[];
@@ -295,6 +327,12 @@ interface HowToStep$1 {
     name?: string;
     url?: string;
     image?: SchemaOrgImage;
+    '@id'?: string;
+    id?: string;
+    totalTime?: string;
+    performTime?: string;
+    prepTime?: string;
+    duration?: string;
 }
 interface HowToSection {
     '@type': 'HowToSection';
@@ -310,6 +348,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 modules that are schemaOrgMappable (as defined in the
+ * modules registry). Non-mappable modules (e.g., nutrition@1, schedule@1)
+ * are excluded from the conversion.
+ */
 declare function toSchemaOrg(recipe: Recipe): SchemaOrgRecipe$1;
 
 interface HowToStep {
@@ -334,110 +380,72 @@ 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 const SOUSTACK_SPEC_VERSION = "0.3.0";
 
-declare function normalizeYield(text: string): string;
-declare function parseYield(text: string): ParsedYield | null;
-declare function formatYield(value: ParsedYield): string;
+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;
 
-/**
- * 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;
+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 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 };
+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 };