soustack 0.2.1 → 0.3.0

package/dist/scrape.d.mts

@@ -0,0 +1,334 @@
+/**
+ * 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") */
+    category?: string;
+    /** Additional tags for filtering */
+    tags?: string[];
+    /** URL(s) to recipe image(s) */
+    image?: string | string[];
+    /** ISO 8601 date string */
+    dateAdded?: string;
+    /** Last updated timestamp */
+    dateModified?: string;
+    source?: Source;
+    yield?: Yield;
+    time?: Time;
+    equipment?: Equipment[];
+    ingredients: IngredientItem[];
+    instructions: InstructionItem[];
+    storage?: Storage;
+    substitutions?: Substitution[];
+    nutrition?: NutritionFacts;
+    metadata?: Record<string, unknown>;
+    [k: `x-${string}`]: unknown;
+}
+type Recipe = SoustackRecipe;
+interface Source {
+    author?: string;
+    url?: string;
+    name?: string;
+    adapted?: boolean;
+}
+interface Yield {
+    amount: number;
+    unit: string;
+    servings?: number;
+    description?: string;
+}
+/**
+ * Time can be structured (machine-readable) or simple (strings).
+ * Structured time takes precedence if both exist.
+ */
+type Time = StructuredTime | SimpleTime;
+interface StructuredTime {
+    prep?: number;
+    active?: number;
+    passive?: number;
+    total?: number;
+}
+interface SimpleTime {
+    prepTime?: string;
+    cookTime?: string;
+}
+interface Equipment {
+    id?: string;
+    name: string;
+    required?: boolean;
+    label?: string;
+    capacity?: Quantity;
+    scalingLimit?: number;
+    alternatives?: string[];
+}
+interface Quantity {
+    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;
+interface IngredientSubsection {
+    subsection: string;
+    items: (string | Ingredient)[];
+}
+interface Ingredient {
+    id?: string;
+    /** Full human-readable text (e.g. "2 cups flour") */
+    item: string;
+    quantity?: Quantity;
+    name?: string;
+    aisle?: string;
+    /** Required prep state (e.g. "diced") */
+    prep?: string;
+    prepAction?: string;
+    prepTime?: number;
+    /** ID of equipment where this ingredient goes */
+    destination?: string;
+    scaling?: Scaling;
+    critical?: boolean;
+    optional?: boolean;
+    notes?: string;
+}
+/**
+ * Intelligent Scaling Logic
+ * Defines how an ingredient behaves when the recipe yield changes.
+ */
+type Scaling = ScalingLinear | ScalingDiscrete | ScalingProportional | ScalingFixed | ScalingBakersPercentage;
+interface ScalingBase {
+    min?: number;
+    max?: number;
+}
+interface ScalingLinear extends ScalingBase {
+    type: "linear";
+}
+interface ScalingDiscrete extends ScalingBase {
+    type: "discrete";
+    roundTo?: number;
+}
+interface ScalingProportional extends ScalingBase {
+    type: "proportional";
+    factor?: number;
+}
+interface ScalingFixed extends ScalingBase {
+    type: "fixed";
+}
+interface ScalingBakersPercentage extends ScalingBase {
+    type: 'bakers_percentage';
+    /** 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;
+}
+type InstructionItem = string | Instruction | InstructionSubsection;
+interface InstructionSubsection {
+    subsection: string;
+    items: (string | Instruction)[];
+}
+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[];
+    timing?: StepTiming;
+    /** Optional image URL for this instruction */
+    image?: string;
+}
+type Instruction = SoustackInstruction;
+interface StepTiming {
+    duration: number | string;
+    type: "active" | "passive";
+    scaling?: "linear" | "fixed" | "sqrt";
+}
+interface Storage {
+    roomTemp?: StorageMethod;
+    refrigerated?: StorageMethod;
+    frozen?: FrozenStorageMethod;
+    reheating?: string;
+    makeAhead?: MakeAheadComponent[];
+}
+interface StorageMethod {
+    /** ISO 8601 duration (e.g. P3D) */
+    duration: string;
+    method?: string;
+    notes?: string;
+}
+interface FrozenStorageMethod extends StorageMethod {
+    thawing?: string;
+}
+interface MakeAheadComponent extends StorageMethod {
+    component: string;
+    storage: "roomTemp" | "refrigerated" | "frozen";
+}
+interface Substitution {
+    ingredient: string;
+    critical?: boolean;
+    notes?: string;
+    alternatives?: Alternative[];
+}
+interface Alternative {
+    name: string;
+    ratio: string;
+    notes?: string;
+    impact?: string;
+    dietary?: string[];
+}
+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 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;
+    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 fetchPage(url: string, options?: FetchOptions): Promise<string>;
+
+export { type FetchImplementation, type FetchOptions, type SchemaOrgRecipe, type ScrapeRecipeOptions, extractRecipeFromHTML, extractSchemaOrgRecipeFromHTML, fetchPage, scrapeRecipe };

package/dist/scrape.d.ts

@@ -0,0 +1,334 @@
+/**
+ * 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") */
+    category?: string;
+    /** Additional tags for filtering */
+    tags?: string[];
+    /** URL(s) to recipe image(s) */
+    image?: string | string[];
+    /** ISO 8601 date string */
+    dateAdded?: string;
+    /** Last updated timestamp */
+    dateModified?: string;
+    source?: Source;
+    yield?: Yield;
+    time?: Time;
+    equipment?: Equipment[];
+    ingredients: IngredientItem[];
+    instructions: InstructionItem[];
+    storage?: Storage;
+    substitutions?: Substitution[];
+    nutrition?: NutritionFacts;
+    metadata?: Record<string, unknown>;
+    [k: `x-${string}`]: unknown;
+}
+type Recipe = SoustackRecipe;
+interface Source {
+    author?: string;
+    url?: string;
+    name?: string;
+    adapted?: boolean;
+}
+interface Yield {
+    amount: number;
+    unit: string;
+    servings?: number;
+    description?: string;
+}
+/**
+ * Time can be structured (machine-readable) or simple (strings).
+ * Structured time takes precedence if both exist.
+ */
+type Time = StructuredTime | SimpleTime;
+interface StructuredTime {
+    prep?: number;
+    active?: number;
+    passive?: number;
+    total?: number;
+}
+interface SimpleTime {
+    prepTime?: string;
+    cookTime?: string;
+}
+interface Equipment {
+    id?: string;
+    name: string;
+    required?: boolean;
+    label?: string;
+    capacity?: Quantity;
+    scalingLimit?: number;
+    alternatives?: string[];
+}
+interface Quantity {
+    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;
+interface IngredientSubsection {
+    subsection: string;
+    items: (string | Ingredient)[];
+}
+interface Ingredient {
+    id?: string;
+    /** Full human-readable text (e.g. "2 cups flour") */
+    item: string;
+    quantity?: Quantity;
+    name?: string;
+    aisle?: string;
+    /** Required prep state (e.g. "diced") */
+    prep?: string;
+    prepAction?: string;
+    prepTime?: number;
+    /** ID of equipment where this ingredient goes */
+    destination?: string;
+    scaling?: Scaling;
+    critical?: boolean;
+    optional?: boolean;
+    notes?: string;
+}
+/**
+ * Intelligent Scaling Logic
+ * Defines how an ingredient behaves when the recipe yield changes.
+ */
+type Scaling = ScalingLinear | ScalingDiscrete | ScalingProportional | ScalingFixed | ScalingBakersPercentage;
+interface ScalingBase {
+    min?: number;
+    max?: number;
+}
+interface ScalingLinear extends ScalingBase {
+    type: "linear";
+}
+interface ScalingDiscrete extends ScalingBase {
+    type: "discrete";
+    roundTo?: number;
+}
+interface ScalingProportional extends ScalingBase {
+    type: "proportional";
+    factor?: number;
+}
+interface ScalingFixed extends ScalingBase {
+    type: "fixed";
+}
+interface ScalingBakersPercentage extends ScalingBase {
+    type: 'bakers_percentage';
+    /** 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;
+}
+type InstructionItem = string | Instruction | InstructionSubsection;
+interface InstructionSubsection {
+    subsection: string;
+    items: (string | Instruction)[];
+}
+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[];
+    timing?: StepTiming;
+    /** Optional image URL for this instruction */
+    image?: string;
+}
+type Instruction = SoustackInstruction;
+interface StepTiming {
+    duration: number | string;
+    type: "active" | "passive";
+    scaling?: "linear" | "fixed" | "sqrt";
+}
+interface Storage {
+    roomTemp?: StorageMethod;
+    refrigerated?: StorageMethod;
+    frozen?: FrozenStorageMethod;
+    reheating?: string;
+    makeAhead?: MakeAheadComponent[];
+}
+interface StorageMethod {
+    /** ISO 8601 duration (e.g. P3D) */
+    duration: string;
+    method?: string;
+    notes?: string;
+}
+interface FrozenStorageMethod extends StorageMethod {
+    thawing?: string;
+}
+interface MakeAheadComponent extends StorageMethod {
+    component: string;
+    storage: "roomTemp" | "refrigerated" | "frozen";
+}
+interface Substitution {
+    ingredient: string;
+    critical?: boolean;
+    notes?: string;
+    alternatives?: Alternative[];
+}
+interface Alternative {
+    name: string;
+    ratio: string;
+    notes?: string;
+    impact?: string;
+    dietary?: string[];
+}
+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 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;
+    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 fetchPage(url: string, options?: FetchOptions): Promise<string>;
+
+export { type FetchImplementation, type FetchOptions, type SchemaOrgRecipe, type ScrapeRecipeOptions, extractRecipeFromHTML, extractSchemaOrgRecipeFromHTML, fetchPage, scrapeRecipe };