tablefacts 0.1.0

package/types/lib/project.d.mts

@@ -0,0 +1,32 @@
+/**
+ * `dir` when given, else TABLEFACTS_PROJECT, else the current folder.
+ * @param {string} [dir]
+ * @returns {string}
+ */
+export declare const projectRoot: (dir?: string) => string;
+/**
+ * A path under <root>/.tablefacts, where output, caches and browser profiles go (git-ignore it).
+ * @param {string | undefined} root project folder (see projectRoot)
+ * @param {...string} parts
+ * @returns {string}
+ */
+export declare const workDirIn: (root: string | undefined, ...parts: string[]) => string;
+/**
+ * A path under <project>/.tablefacts for the project in TABLEFACTS_PROJECT or the current folder.
+ * @param {...string} parts
+ * @returns {string}
+ */
+export declare const workDir: (...parts: string[]) => string;
+/**
+ * The env files read, first one wins: <root>/.env, then <root>/data/.env (older templates).
+ * @param {string} [root] project folder (see projectRoot)
+ * @returns {string[]}
+ */
+export declare const envFiles: (root?: string) => string[];
+/**
+ * An absolute path: relative paths resolve against the project (`projectDir`) when given, else the current folder.
+ * @param {string | undefined} projectDir
+ * @param {string} path
+ * @returns {string}
+ */
+export declare const resolveIn: (projectDir: string | undefined, path: string) => string;

package/types/lib/text.d.mts

@@ -0,0 +1,4 @@
+/** Lowercase and accent-free, to compare names typed by different people. */
+export declare const fold: (s: any) => string;
+/** "Café Ñandú & Co." to "cafe-nandu-co" (empty when nothing letter-like is left). */
+export declare const slugify: (s: any) => string;

package/types/lib/types.d.mts

@@ -0,0 +1,668 @@
+export type Log = (message: string, level?: 'info' | 'warn' | 'error') => void;
+export type Env = Record<string, string | undefined>;
+export type ResearchOptions = {
+    /**
+     * Restaurant name. Required.
+     */
+    name: string;
+    /**
+     * "City, Country".
+     */
+    location?: string;
+    /**
+     * ISO country code, narrows the search (CO, MX, US...).
+     */
+    country?: string;
+    website?: string;
+    /**
+     * Handle or URL.
+     */
+    instagram?: string;
+    /**
+     * TripAdvisor page URL.
+     */
+    tripadvisor?: string;
+    /**
+     * Linktree or other link-in-bio page.
+     */
+    linktree?: string;
+    /**
+     * Also download up to n Google and n website photos (reference only).
+     */
+    photos?: number;
+    /**
+     * Render the website with Playwright (sites built in JavaScript).
+     */
+    render?: boolean;
+    /**
+     * Set false to skip Google even if a key is available. Default true.
+     */
+    google?: boolean;
+    /**
+     * Default: env.GOOGLE_PLACES_API_KEY.
+     */
+    googleKey?: string;
+    /**
+     * Environment the keys are read from. Default process.env.
+     */
+    env?: Env;
+    /**
+     * Output folder; relative paths resolve against projectDir. Default <project>/.tablefacts/research/<slug>.
+     */
+    out?: string;
+    /**
+     * Project folder. Default: TABLEFACTS_PROJECT or the current folder.
+     */
+    projectDir?: string;
+    log?: Log;
+};
+export type ResearchPhoto = {
+    /**
+     * File name inside <outDir>/photos.
+     */
+    file: string;
+    /**
+     * Where it was downloaded from.
+     */
+    source: string;
+    alt?: string;
+};
+export type ResearchProfile = {
+    /**
+     * Each field carries value, source and confidence.
+     */
+    fields: Record<string, any>;
+    warnings?: string[];
+};
+export type ResearchResult = {
+    /**
+     * The merged profile.
+     */
+    profile: ResearchProfile;
+    /**
+     * What each source found or failed to find.
+     */
+    notes: string[];
+    photos: ResearchPhoto[];
+    /**
+     * Absolute output folder.
+     */
+    outDir: string;
+    /**
+     * Absolute paths of the written files.
+     */
+    files: {
+        profile: string;
+        report: string;
+        setupAnswers: string;
+    };
+};
+export type PhotoFailure = {
+    /**
+     * The post, profile or page that failed.
+     */
+    item: string;
+    reason: string;
+};
+export type PhotoSummary = {
+    saved: number;
+    /**
+     * Files that were already there.
+     */
+    skipped: number;
+    failed: PhotoFailure[];
+    /**
+     * Only present when dryRun is true.
+     */
+    found?: {
+        name: string;
+        url: string;
+    }[];
+};
+export type InstagramOptions = {
+    /**
+     * Post links.
+     */
+    links?: string[];
+    /**
+     * Text file with one link per line (resolved against projectDir).
+     */
+    file?: string;
+    /**
+     * Folder the images are saved to (resolved against projectDir). Required.
+     */
+    out: string;
+    /**
+     * Profile link or handle (with or without the at sign): download a whole profile (videos skipped).
+     */
+    profile?: string;
+    /**
+     * With `profile`, batches of posts to load. Default 1.
+     */
+    pages?: number | 'all';
+    /**
+     * Edge debugging address, e.g. http://localhost:9222. Started if nothing listens.
+     */
+    cdp?: string;
+    /**
+     * Profile folder for the Edge that is started.
+     */
+    edgeDir?: string;
+    /**
+     * Reach toolzu through a Google search (CLI: --google). Default false.
+     */
+    viaGoogle?: boolean;
+    /**
+     * Installed browser channel: 'msedge' or 'chrome'.
+     */
+    browser?: string;
+    /**
+     * Persistent browser profile (resolved against projectDir).
+     */
+    userDataDir?: string;
+    /**
+     * Project folder. Default: TABLEFACTS_PROJECT or the current folder.
+     */
+    projectDir?: string;
+    /**
+     * Show the browser window.
+     */
+    headed?: boolean;
+    /**
+     * List what would be saved without saving.
+     */
+    dryRun?: boolean;
+    /**
+     * Keep screenshots in <out>/_debug.
+     */
+    debug?: boolean;
+    log?: Log;
+};
+export type TripadvisorOptions = {
+    /**
+     * Restaurant page links. At least one valid link is required.
+     */
+    links: string[];
+    /**
+     * Folder the images are saved to (resolved against projectDir). Required.
+     */
+    out: string;
+    /**
+     * Edge debugging address. Default http://localhost:9222.
+     */
+    cdp?: string;
+    /**
+     * Profile folder for the Edge that is started.
+     */
+    edgeDir?: string;
+    /**
+     * Stop after n photos per restaurant.
+     */
+    max?: number;
+    /**
+     * Project folder. Default: TABLEFACTS_PROJECT or the current folder.
+     */
+    projectDir?: string;
+    dryRun?: boolean;
+    debug?: boolean;
+    log?: Log;
+};
+export type MenuProduct = {
+    name: string;
+    description?: string | null;
+    /**
+     * Finite and not negative.
+     */
+    price: number;
+    /**
+     * ISO 4217 code, e.g. COP.
+     */
+    currency: string;
+    /**
+     * An https URL.
+     */
+    image_url?: string | null;
+    recommended?: boolean;
+};
+export type MenuSection = {
+    name: string;
+    products: MenuProduct[];
+};
+export type MenuCategory = {
+    /**
+     * The key the site's dictionaries use.
+     */
+    slug: string;
+    name: string;
+    sections: MenuSection[];
+};
+export type Menu = MenuCategory[];
+export type MenuTotals = {
+    categories: number;
+    sections: number;
+    products: number;
+    withImage: number;
+};
+export type ImportOptions = {
+    /**
+     * Check and report, write nothing.
+     */
+    dryRun?: boolean;
+    /**
+     * Also save the extracted menu as JSON at this path (resolved against projectDir).
+     */
+    json?: string;
+    /**
+     * Replace the whole menu, not only the categories in this import.
+     */
+    replaceAll?: boolean;
+    /**
+     * Write even if the import has far fewer products than it replaces.
+     */
+    force?: boolean;
+    /**
+     * Default: env.SUPABASE_DB_URL.
+     */
+    databaseUrl?: string;
+    /**
+     * Environment the database URL and keys are read from. Default process.env.
+     */
+    env?: Env;
+    /**
+     * Project folder. Default: TABLEFACTS_PROJECT or the current folder.
+     */
+    projectDir?: string;
+    log?: Log;
+};
+export type ImportResult = {
+    totals: MenuTotals;
+    notes: string[];
+    written: boolean;
+    dryRun: boolean;
+    /**
+     * Null when the database was not reached.
+     */
+    database: {
+        label: string;
+        current: {
+            categories: number;
+            products: number;
+            kept: string[];
+        };
+    } | null;
+};
+export type ImportMenuOptions = ImportOptions & {
+    menu: Menu;
+    notes?: string[];
+    title?: string;
+};
+export type CluviConfig = {
+    /**
+     * Any page of the restaurant's Cluvi menu.
+     */
+    url?: string;
+    /**
+     * Cluvi main categories folded into each site category.
+     */
+    categories?: {
+        slug: string;
+        name: string;
+        from: string[];
+    }[];
+    /**
+     * Cluvi subcategory to section name.
+     */
+    sections?: Record<string, string>;
+};
+export type RawConfig = {
+    /**
+     * Page with the menu pictures, or a direct image URL.
+     */
+    url?: string;
+    /**
+     * ISO code of the prices.
+     */
+    currency: string;
+    /**
+     * Thousands separator the menu prints. Default ".".
+     */
+    thousands?: string;
+    /**
+     * Decimal separator the menu prints. Default ",".
+     */
+    decimal?: string;
+    /**
+     * Multiplies every price. Default 1.
+     */
+    scale?: number;
+    /**
+     * Category that lists each group.
+     */
+    categories?: {
+        slug: string;
+        name: string;
+        groups?: ('food' | 'drink')[];
+    }[];
+    /**
+     * Section title to category slug.
+     */
+    placeIn?: Record<string, string>;
+    /**
+     * Section title to the name stored.
+     */
+    sections?: Record<string, string>;
+    /**
+     * Section titles to leave out.
+     */
+    skipSections?: string[];
+};
+export type MenuSourceConfig = CluviConfig | RawConfig;
+export type CluviMenuOptions = {
+    /**
+     * Default: the config's.
+     */
+    url?: string;
+    service?: 'on_table' | 'delivery' | 'take_away';
+    lang?: string;
+    /**
+     * Default: the cluvi config.mjs.
+     */
+    config?: CluviConfig;
+};
+export type ImportCluviOptions = ImportOptions & CluviMenuOptions;
+export type ImageMenuReadOptions = {
+    /**
+     * Pages or image URLs. Default: the config's url.
+     */
+    urls?: string[];
+    /**
+     * Pages to read, e.g. '1,3-5' or [1, 3, 4, 5].
+     */
+    only?: string | number[];
+    /**
+     * Vision provider, see `providers`. Default MENU_VISION_PROVIDER or `defaultProvider`.
+     */
+    provider?: string;
+    model?: string;
+    /**
+     * Ignore images declaring a smaller width. Default 500.
+     */
+    minWidth?: number;
+    /**
+     * Default: the provider's key in env.
+     */
+    apiKey?: string;
+    /**
+     * Read the pages again instead of using the saved transcriptions.
+     */
+    refresh?: boolean;
+    /**
+     * Default: the raw config.mjs.
+     */
+    config?: RawConfig;
+};
+export type ImportImageMenuOptions = ImportOptions & ImageMenuReadOptions;
+export type ListMenuImagesOptions = {
+    urls?: string[];
+    only?: string | number[];
+    minWidth?: number;
+    config?: RawConfig;
+};
+export type MenuImage = {
+    /**
+     * Position as the CLI's --list numbers it.
+     */
+    number: number;
+    url: string;
+    alt: string;
+};
+export type PriceFormat = {
+    /**
+     * Default ".".
+     */
+    thousands?: string;
+    /**
+     * Default ",".
+     */
+    decimal?: string;
+    /**
+     * Default 1.
+     */
+    scale?: number;
+};
+export type VisionProvider = {
+    label: string;
+    /**
+     * Environment variable holding the API key.
+     */
+    keyName: string;
+    defaultModel: string;
+};
+export type LoadEnvOptions = {
+    /**
+     * Project folder whose .env files are read.
+     */
+    projectDir?: string;
+    /**
+     * Exactly these files instead of the project's.
+     */
+    files?: string[];
+    /**
+     * Object the variables are set on. Default process.env.
+     */
+    env?: Env;
+};
+export type TablefactsErrorCode = 'EUSAGE' | 'ECONFIG' | 'EDEPENDENCY' | 'EFAILED';
+/**
+ * Progress callback. `level` is 'info' by default; 'warn' for problems the run goes on from,
+ * 'error' for failures. Every tool is silent unless given one.
+ * @typedef {(message: string, level?: 'info' | 'warn' | 'error') => void} Log
+ */
+/**
+ * An environment object such as process.env.
+ * @typedef {Record<string, string | undefined>} Env
+ */
+/**
+ * @typedef {object} ResearchOptions
+ * @property {string} name Restaurant name. Required.
+ * @property {string} [location] "City, Country".
+ * @property {string} [country] ISO country code, narrows the search (CO, MX, US...).
+ * @property {string} [website]
+ * @property {string} [instagram] Handle or URL.
+ * @property {string} [tripadvisor] TripAdvisor page URL.
+ * @property {string} [linktree] Linktree or other link-in-bio page.
+ * @property {number} [photos] Also download up to n Google and n website photos (reference only).
+ * @property {boolean} [render] Render the website with Playwright (sites built in JavaScript).
+ * @property {boolean} [google] Set false to skip Google even if a key is available. Default true.
+ * @property {string} [googleKey] Default: env.GOOGLE_PLACES_API_KEY.
+ * @property {Env} [env] Environment the keys are read from. Default process.env.
+ * @property {string} [out] Output folder; relative paths resolve against projectDir. Default <project>/.tablefacts/research/<slug>.
+ * @property {string} [projectDir] Project folder. Default: TABLEFACTS_PROJECT or the current folder.
+ * @property {Log} [log]
+ */
+/**
+ * @typedef {object} ResearchPhoto
+ * @property {string} file File name inside <outDir>/photos.
+ * @property {string} source Where it was downloaded from.
+ * @property {string} [alt]
+ */
+/**
+ * @typedef {object} ResearchProfile
+ * @property {Record<string, any>} fields Each field carries value, source and confidence.
+ * @property {string[]} [warnings]
+ */
+/**
+ * @typedef {object} ResearchResult
+ * @property {ResearchProfile} profile The merged profile.
+ * @property {string[]} notes What each source found or failed to find.
+ * @property {ResearchPhoto[]} photos
+ * @property {string} outDir Absolute output folder.
+ * @property {{ profile: string, report: string, setupAnswers: string }} files Absolute paths of the written files.
+ */
+/**
+ * @typedef {object} PhotoFailure
+ * @property {string} item The post, profile or page that failed.
+ * @property {string} reason
+ */
+/**
+ * @typedef {object} PhotoSummary
+ * @property {number} saved
+ * @property {number} skipped Files that were already there.
+ * @property {PhotoFailure[]} failed
+ * @property {{ name: string, url: string }[]} [found] Only present when dryRun is true.
+ */
+/**
+ * At least one of `links`, `file` or `profile` is required.
+ * @typedef {object} InstagramOptions
+ * @property {string[]} [links] Post links.
+ * @property {string} [file] Text file with one link per line (resolved against projectDir).
+ * @property {string} out Folder the images are saved to (resolved against projectDir). Required.
+ * @property {string} [profile] Profile link or handle (with or without the at sign): download a whole profile (videos skipped).
+ * @property {number | 'all'} [pages] With `profile`, batches of posts to load. Default 1.
+ * @property {string} [cdp] Edge debugging address, e.g. http://localhost:9222. Started if nothing listens.
+ * @property {string} [edgeDir] Profile folder for the Edge that is started.
+ * @property {boolean} [viaGoogle] Reach toolzu through a Google search (CLI: --google). Default false.
+ * @property {string} [browser] Installed browser channel: 'msedge' or 'chrome'.
+ * @property {string} [userDataDir] Persistent browser profile (resolved against projectDir).
+ * @property {string} [projectDir] Project folder. Default: TABLEFACTS_PROJECT or the current folder.
+ * @property {boolean} [headed] Show the browser window.
+ * @property {boolean} [dryRun] List what would be saved without saving.
+ * @property {boolean} [debug] Keep screenshots in <out>/_debug.
+ * @property {Log} [log]
+ */
+/**
+ * @typedef {object} TripadvisorOptions
+ * @property {string[]} links Restaurant page links. At least one valid link is required.
+ * @property {string} out Folder the images are saved to (resolved against projectDir). Required.
+ * @property {string} [cdp] Edge debugging address. Default http://localhost:9222.
+ * @property {string} [edgeDir] Profile folder for the Edge that is started.
+ * @property {number} [max] Stop after n photos per restaurant.
+ * @property {string} [projectDir] Project folder. Default: TABLEFACTS_PROJECT or the current folder.
+ * @property {boolean} [dryRun]
+ * @property {boolean} [debug]
+ * @property {Log} [log]
+ */
+/**
+ * @typedef {object} MenuProduct
+ * @property {string} name
+ * @property {string | null} [description]
+ * @property {number} price Finite and not negative.
+ * @property {string} currency ISO 4217 code, e.g. COP.
+ * @property {string | null} [image_url] An https URL.
+ * @property {boolean} [recommended]
+ */
+/**
+ * @typedef {object} MenuSection
+ * @property {string} name
+ * @property {MenuProduct[]} products
+ */
+/**
+ * @typedef {object} MenuCategory
+ * @property {string} slug The key the site's dictionaries use.
+ * @property {string} name
+ * @property {MenuSection[]} sections
+ */
+/** @typedef {MenuCategory[]} Menu */
+/**
+ * @typedef {object} MenuTotals
+ * @property {number} categories
+ * @property {number} sections
+ * @property {number} products
+ * @property {number} withImage
+ */
+/**
+ * @typedef {object} ImportOptions
+ * @property {boolean} [dryRun] Check and report, write nothing.
+ * @property {string} [json] Also save the extracted menu as JSON at this path (resolved against projectDir).
+ * @property {boolean} [replaceAll] Replace the whole menu, not only the categories in this import.
+ * @property {boolean} [force] Write even if the import has far fewer products than it replaces.
+ * @property {string} [databaseUrl] Default: env.SUPABASE_DB_URL.
+ * @property {Env} [env] Environment the database URL and keys are read from. Default process.env.
+ * @property {string} [projectDir] Project folder. Default: TABLEFACTS_PROJECT or the current folder.
+ * @property {Log} [log]
+ */
+/**
+ * @typedef {object} ImportResult
+ * @property {MenuTotals} totals
+ * @property {string[]} notes
+ * @property {boolean} written
+ * @property {boolean} dryRun
+ * @property {{ label: string, current: { categories: number, products: number, kept: string[] } } | null} database Null when the database was not reached.
+ */
+/**
+ * @typedef {ImportOptions & { menu: Menu, notes?: string[], title?: string }} ImportMenuOptions
+ */
+/**
+ * Restaurant-specific part of the Cluvi source (src/menu/cluvi/config.mjs).
+ * @typedef {object} CluviConfig
+ * @property {string} [url] Any page of the restaurant's Cluvi menu.
+ * @property {{ slug: string, name: string, from: string[] }[]} [categories] Cluvi main categories folded into each site category.
+ * @property {Record<string, string>} [sections] Cluvi subcategory to section name.
+ */
+/**
+ * Restaurant-specific part of the picture-menu source (src/menu/raw/config.mjs).
+ * @typedef {object} RawConfig
+ * @property {string} [url] Page with the menu pictures, or a direct image URL.
+ * @property {string} currency ISO code of the prices.
+ * @property {string} [thousands] Thousands separator the menu prints. Default ".".
+ * @property {string} [decimal] Decimal separator the menu prints. Default ",".
+ * @property {number} [scale] Multiplies every price. Default 1.
+ * @property {{ slug: string, name: string, groups?: ('food' | 'drink')[] }[]} [categories] Category that lists each group.
+ * @property {Record<string, string>} [placeIn] Section title to category slug.
+ * @property {Record<string, string>} [sections] Section title to the name stored.
+ * @property {string[]} [skipSections] Section titles to leave out.
+ */
+/** @typedef {CluviConfig | RawConfig} MenuSourceConfig */
+/**
+ * @typedef {object} CluviMenuOptions
+ * @property {string} [url] Default: the config's.
+ * @property {'on_table' | 'delivery' | 'take_away'} [service]
+ * @property {string} [lang]
+ * @property {CluviConfig} [config] Default: the cluvi config.mjs.
+ */
+/** @typedef {ImportOptions & CluviMenuOptions} ImportCluviOptions */
+/**
+ * @typedef {object} ImageMenuReadOptions
+ * @property {string[]} [urls] Pages or image URLs. Default: the config's url.
+ * @property {string | number[]} [only] Pages to read, e.g. '1,3-5' or [1, 3, 4, 5].
+ * @property {string} [provider] Vision provider, see `providers`. Default MENU_VISION_PROVIDER or `defaultProvider`.
+ * @property {string} [model]
+ * @property {number} [minWidth] Ignore images declaring a smaller width. Default 500.
+ * @property {string} [apiKey] Default: the provider's key in env.
+ * @property {boolean} [refresh] Read the pages again instead of using the saved transcriptions.
+ * @property {RawConfig} [config] Default: the raw config.mjs.
+ */
+/** @typedef {ImportOptions & ImageMenuReadOptions} ImportImageMenuOptions */
+/**
+ * @typedef {object} ListMenuImagesOptions
+ * @property {string[]} [urls]
+ * @property {string | number[]} [only]
+ * @property {number} [minWidth]
+ * @property {RawConfig} [config]
+ */
+/**
+ * @typedef {object} MenuImage
+ * @property {number} number Position as the CLI's --list numbers it.
+ * @property {string} url
+ * @property {string} alt
+ */
+/**
+ * @typedef {object} PriceFormat
+ * @property {string} [thousands] Default ".".
+ * @property {string} [decimal] Default ",".
+ * @property {number} [scale] Default 1.
+ */
+/**
+ * @typedef {object} VisionProvider
+ * @property {string} label
+ * @property {string} keyName Environment variable holding the API key.
+ * @property {string} defaultModel
+ */
+/**
+ * @typedef {object} LoadEnvOptions
+ * @property {string} [projectDir] Project folder whose .env files are read.
+ * @property {string[]} [files] Exactly these files instead of the project's.
+ * @property {Env} [env] Object the variables are set on. Default process.env.
+ */
+/** @typedef {'EUSAGE' | 'ECONFIG' | 'EDEPENDENCY' | 'EFAILED'} TablefactsErrorCode */
+export {};