@curless/shopify-storefront 0.1.0

package/dist/tools.js

@@ -0,0 +1,779 @@
+import { cartPermalink, lookupShopifyOrder, resolveVariant, snapChoices, } from '@curless/shopify-adapter';
+// OpenAI's Apps review requires all three hints on every tool. All four read
+// the merchant's own store and change nothing, in it or anywhere else.
+//
+// Anthropic's checklist additionally requires a `title` on every tool, and it is
+// not decoration: the hints decide auto-permissions, and the title is the name a
+// buyer reads in the permission line. `${deps.tools.checkout}` is the reason to
+// care — a tool whose NAME says "create" is asked about in the buyer's language,
+// and "Get a Moody checkout link" is what it actually does.
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
+const reads = (title) => ({ ...READ_ONLY, title });
+/**
+ * The tool table, built for THIS storefront's names.
+ *
+ * A constant until there was a second merchant. A model choosing among
+ * several storefront connectors picks by tool name, so the names carry the
+ * merchant — and that means they cannot be literals here.
+ */
+export const buildTools = (n, v) => [
+    {
+        name: n.list,
+        // The first clause says what this READS, not what to use it instead of.
+        //
+        // It said "use this INSTEAD of web search" for a day, written after watching
+        // an assistant answer "Moody brown dailies" from the scraped storefront —
+        // £14.84 in one paragraph and "$19.99–$24.99 USD" two below it, nothing
+        // about stock, not one orderable prescription. But Anthropic's criteria
+        // reject descriptions that "interfere with Claude calling other tools", and
+        // that sentence is exactly the shape they name.
+        //
+        // Nothing informative was lost. What could ever have moved the decision is
+        // the capability — live catalogue, real stock, prescriptions that can be
+        // ordered — and that is a fact about this tool. The imperative was the part
+        // arguing with the other tools, and arguing was never what worked.
+        description: `Open the ${v.merchant} storefront — the live catalogue of the shop itself: the price it charges today, what it can actually ship, and the combinations it will accept, rendered as a card the buyer can buy from. Call this FIRST, with NO arguments, as soon as the buyer wants ${v.nounPlural} — it renders a card with pictures, filter chips and a Buy button on every ${v.noun}, so they can browse and choose without being asked anything. Do not interview them first and do not recommend on top of it. Pass \`query\` only once they have said what they want.${v.hints.browse ? ` ${v.hints.browse}` : ''}`,
+        annotations: reads(`Browse ${v.merchant} ${v.nounPlural}`),
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Free text over the name, tags and description — this is how colour is searched ("green", "brown", "matcha")',
+                },
+                maxPrice: { type: 'number', description: 'Upper bound in whole currency units' },
+                limit: { type: 'number', description: 'Default 20' },
+            },
+        },
+    },
+    {
+        name: n.get,
+        description: `One ${v.noun} in full: its options, every value offered, prices and images. Check this BEFORE checkout — how many choices the buyer must make is set by the product, not fixed, so read them here rather than assuming.${v.hints.product ? ` ${v.hints.product}` : ''}`,
+        annotations: reads(`View one ${v.merchant} ${v.noun}`),
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: {
+                    type: 'string',
+                    description: `The ${v.noun} name or handle${v.hints.example ? `, e.g. "${v.hints.example}"` : ''}`,
+                },
+            },
+            required: ['product'],
+        },
+    },
+    {
+        name: n.checkout,
+        description: `Get the checkout link for ONE specific ${v.noun} variant. Fill EVERY option the product has — if it offers two, both are required, and they are usually different. Never assume one answer carries to another option, and never round to a nearby value: ask. If the choices do not name exactly one variant this returns the options to ask about instead of guessing.${v.hints.checkout ? ` ${v.hints.checkout}` : ''}`,
+        annotations: reads(`Get a ${v.merchant} checkout link`),
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: `The ${v.noun} name or handle` },
+                options: {
+                    type: 'object',
+                    // The SHAPE is generic; the example is not, so it comes from the
+                    // merchant. A pet shop reading {"Left":"-2.00"} learns nothing except
+                    // that this tool was written for someone else.
+                    description: `One value per option, keyed by the store's own option names.${v.hints.checkout ? ` ${v.hints.checkout}` : ''}`,
+                    additionalProperties: { type: 'string' },
+                },
+                quantity: { type: 'number', description: 'Default 1' },
+            },
+            required: ['product', 'options'],
+        },
+    },
+    {
+        name: n.lookupOrder,
+        description: 'Find an order the buyer already placed. BOTH the order number and the email it was placed with are required — that pair is what proves the order is theirs.',
+        annotations: reads(`Look up a ${v.merchant} order`),
+        inputSchema: {
+            type: 'object',
+            properties: {
+                orderNumber: { type: 'string', description: 'From the confirmation email, e.g. "#1052"' },
+                email: { type: 'string', description: 'The email the order was placed with' },
+            },
+            required: ['orderNumber', 'email'],
+        },
+    },
+];
+// The shape of each tool's `structuredContent`, so the model knows what it is
+// holding without inferring it from one example.
+//
+// EVERY tool can return more than one shape — `${deps.tools.checkout}` answers
+// `checkout`, `needs-options`, `out-of-stock` or `error` depending on what the
+// buyer gave it — so `view` is the discriminator and is always present. That is
+// the part a reader must be able to rely on, so it is the part declared exactly.
+//
+// Item internals are left open on purpose. A schema that promises fields the
+// payload sometimes omits is worse than no schema: it is a claim that is
+// sometimes false, and the reader trusting it is the model deciding what to say
+// to a buyer.
+const OBJ = { type: 'object' };
+const ARR = { type: 'array', items: { type: 'object' } };
+const STR = { type: 'string' };
+export const buildOutputSchemas = (n) => ({
+    [n.list]: {
+        type: 'object',
+        properties: {
+            view: { const: 'products' },
+            merchant: STR,
+            logoUrl: STR,
+            toolNames: OBJ,
+            vocab: OBJ,
+            products: ARR,
+            total: { type: 'number' },
+            facets: ARR,
+            promotions: ARR,
+            // Set when the answer is broader than what was asked — the assistant
+            // should not read a relaxed result as an exact match.
+            relaxedFrom: STR,
+        },
+        required: ['view', 'products'],
+    },
+    [n.get]: {
+        type: 'object',
+        properties: {
+            view: { enum: ['product', 'error'] },
+            merchant: STR,
+            logoUrl: STR,
+            toolNames: OBJ,
+            vocab: OBJ,
+            // `options` is what the buyer must still answer; `inStock` is which
+            // combinations of those can actually be bought.
+            product: OBJ,
+            error: STR,
+        },
+        required: ['view'],
+    },
+    [n.checkout]: {
+        type: 'object',
+        properties: {
+            view: { enum: ['checkout', 'needs-options', 'out-of-stock', 'error'] },
+            merchant: STR,
+            logoUrl: STR,
+            toolNames: OBJ,
+            vocab: OBJ,
+            product: OBJ,
+            // view=checkout
+            variant: OBJ,
+            quantity: { type: 'number' },
+            total: STR,
+            checkoutUrl: STR,
+            // view=needs-options — what is still missing, and what was understood so
+            // far, already snapped to the store's own values.
+            options: ARR,
+            given: OBJ,
+            eyes: { enum: ['pair', 'single', 'unknown'] },
+            inStock: ARR,
+            error: STR,
+        },
+        required: ['view'],
+    },
+    [n.lookupOrder]: {
+        type: 'object',
+        properties: {
+            // `order-not-found` is returned both for no such order AND for a wrong
+            // email — deliberately indistinguishable.
+            view: { enum: ['order', 'order-not-found', 'rate-limited'] },
+            merchant: STR,
+            logoUrl: STR,
+            toolNames: OBJ,
+            vocab: OBJ,
+            order: OBJ,
+        },
+        required: ['view'],
+    },
+});
+// Colour words → what this store actually calls its lenses. The colour IS the
+// product name here ("Matcha Green", "Oolong Brown"), so a buyer asking for a
+// family — in either language — matches nothing without this. Not a translation
+// table: only the words a lens shopper reaches for.
+//
+// Keyed on the BARE colour. A picker offering "灰/蓝色系" sends 蓝色系, and
+// enumerating every suffix by hand is how 绿色系 and 棕色系 ended up mapped while
+// 蓝色系 and 紫色系 silently fell through to the whole 382-product shelf.
+const COLOUR_WORDS = {
+    棕: ['brown', 'choco', 'coffee', 'oolong', 'walnut', 'caramel', 'hazel', 'barley'],
+    咖啡: ['brown', 'coffee', 'choco'],
+    brown: ['choco', 'coffee', 'oolong', 'walnut', 'caramel', 'hazel'],
+    绿: ['green', 'matcha', 'olive', 'jade', 'mint', 'sage'],
+    green: ['matcha', 'olive', 'jade', 'mint', 'sage'],
+    灰: ['grey', 'gray', 'smoke', 'ash', 'silver', 'granite'],
+    grey: ['gray', 'smoke', 'ash', 'silver'],
+    gray: ['grey', 'smoke', 'ash', 'silver'],
+    蓝: ['blue', 'ocean', 'sky', 'aqua', 'denim'],
+    blue: ['ocean', 'sky', 'aqua', 'denim'],
+    紫: ['purple', 'violet', 'lilac', 'lavender', 'taro'],
+    purple: ['violet', 'lilac', 'lavender', 'taro'],
+    粉: ['pink', 'rose', 'peach', 'berry', 'sakura', 'coral'],
+    pink: ['rose', 'peach', 'berry', 'sakura', 'coral'],
+    黑: ['black', 'noir', 'onyx', 'halo'],
+    black: ['noir', 'onyx'],
+    日抛: ['1 day'],
+    月抛: ['1 month'],
+    半年抛: ['6 months'],
+    自然: ['natural', 'nude', 'daily'],
+};
+// "蓝色系" / "蓝色" / "蓝" are one key. Trimmed rather than enumerated, so a
+// phrasing nobody thought of still lands on the colour.
+const colourKey = (w) => w.replace(/(色系|色调|系|色)$/u, '') || w;
+// The filter chips, taken from the merchant's OWN taxonomy.
+//
+// Moody's site files a lens under By Style / By Color / By G.Diameter /
+// Replacement cycle, and their tags land on exactly those axes: Brown(26),
+// Grey(7); With Limbal ring(49), Glowy Highlight(28); 1 Day(36), 6 Months(3).
+// A flat row of the six commonest tags — which is what this was — mixes a colour
+// with a product line and a lens finish, and asks the buyer to spot the
+// difference. Grouped, each row answers one question.
+//
+// Two corrections their own site made obvious:
+//
+//   • DIAMETER IS A FILTER, and I had been throwing it away. The tags are bare
+//     numbers (14.2, 13.5), which the old rule called noise along with base
+//     curve and water content — but Moody offers G.Diameter as a top-level
+//     choice, bucketed. Bucketed here too, at their thresholds.
+//   • Base curve (8.6) and water content (55%) really are specs, not filters.
+//     They appear on their spec sheets and in none of their filter menus.
+const DIAMETER_BUCKETS = [
+    { label: 'Large ≥13.7mm', min: 13.7, max: 99 },
+    { label: 'Medium 13.4–13.6mm', min: 13.4, max: 13.69 },
+    { label: 'Small ≤13.3mm', min: 0, max: 13.39 },
+];
+// A lens diameter, or null. Base curve (8.x) and water content (n%) are excluded
+// by range and by shape — 8.6 is not a small lens, it is a curve.
+const asDiameter = (tag) => {
+    if (!/^\d{2}(\.\d)?$/.test(tag))
+        return null;
+    const n = Number(tag);
+    return n >= 12 && n <= 16 ? n : null;
+};
+const AXES = [
+    { axis: 'Colour', match: /^(brown|green|blue|black|gr[ae]y|pink|red|purple|gold[\s\w]*)$/i },
+    {
+        axis: 'Style',
+        match: /^(with limbal ring|without limbal ring|glowy highlight|iris pattern|bold|neutral)$/i,
+    },
+    { axis: 'Cycle', match: /^(1 day|1 month|6 months|1 year|trials?)$/i },
+];
+// An axis is worth offering when its choices tell results apart. Judged on the
+// AXIS, never on the individual value — dropping a value because everything has
+// it deletes a true option from a row of alternatives, and the buyer reads the
+// absence as an answer.
+//
+// That is not hypothetical: a lens is tagged with every diameter it comes in, so
+// all 40 results offered a large size, and the value-level rule silently removed
+// "Large ≥13.7mm" while keeping Medium and Small. The row then said this store
+// has no large lenses — about the diameters it stocks most.
+const worthOffering = (values, total) => values.length > 1 && values.some((v) => v.count < total);
+const facetsOf = (products) => {
+    if (products.length < 3)
+        return [];
+    const covers = (tags) => products.filter((p) => (p.tags ?? []).some((t) => tags.includes(t))).length;
+    const out = [];
+    for (const { axis, match } of AXES) {
+        const tags = new Set();
+        for (const p of products)
+            for (const t of p.tags ?? [])
+                if (match.test(t))
+                    tags.add(t);
+        const values = [...tags]
+            .map((t) => ({ label: t, tags: [t], count: covers([t]) }))
+            .filter((v) => v.count > 0)
+            .sort((a, b) => b.count - a.count);
+        if (worthOffering(values, products.length))
+            out.push({ axis, values });
+    }
+    // Diameter, bucketed at Moody's own thresholds rather than offering twelve
+    // bare numbers.
+    const diameters = new Set();
+    for (const p of products)
+        for (const t of p.tags ?? [])
+            if (asDiameter(t) !== null)
+                diameters.add(t);
+    if (diameters.size > 1) {
+        const values = DIAMETER_BUCKETS.map(({ label, min, max }) => {
+            const tags = [...diameters].filter((t) => {
+                const n = asDiameter(t);
+                return n >= min && n <= max;
+            });
+            return { label, tags, count: covers(tags) };
+        }).filter((v) => v.count > 0);
+        if (worthOffering(values, products.length))
+            out.push({ axis: 'Diameter', values });
+    }
+    return out;
+};
+// The combinations a buyer can actually buy, as option maps — the one thing the
+// option lists cannot express. "Left -5.75 is offered" and "Right -5.50 is
+// offered" says nothing about whether that PAIR exists, and at this store 674 of
+// the 676 pairs do not.
+const inStockCombos = (variants) => {
+    const stocked = variants.filter((v) => v.available);
+    return {
+        inStock: stocked
+            .slice(0, IN_STOCK_CAP)
+            .map((v) => Object.fromEntries(v.options.map((o) => [o.name, o.value]))),
+        // Tells the picker to stop filtering rather than filter on a truncated list,
+        // which would hide buyable prescriptions.
+        inStockTruncated: stocked.length > IN_STOCK_CAP,
+    };
+};
+// How many in-stock combinations a product payload carries. Generous, because
+// the list is what stops the picker offering prescriptions nobody can buy, and
+// stingy enough that a fully stocked pair (676) cannot flood a tool result the
+// model also has to read.
+const IN_STOCK_CAP = 300;
+// The shop's offers, as the card and the assistant both need them: the
+// merchant's own wording, which is usually the whole story — they write "Buy 2
+// get 5% OFF | Buy 3 get 10% OFF" precisely because that is what a shopper reads.
+//
+// `promotionsBlocked` says WHY there are none when the reason is not "there are
+// none". Those need a scope granted at install, so the honest answer to a
+// merchant asking why their sale is invisible is "reinstall the app", and that
+// answer only exists if we keep the distinction.
+const promoPayload = (deps) => {
+    const snap = deps.catalog.current;
+    const promotions = snap.discounts
+        .map((d) => ({
+        title: d.title,
+        ...(d.percentage !== undefined ? { percentOff: Math.round(d.percentage * 100) } : {}),
+        ...(d.minQuantity !== undefined ? { minQuantity: d.minQuantity } : {}),
+        ...(d.endsAt ? { endsAt: d.endsAt } : {}),
+    }))
+        // Only offers a shopper can act on.
+        //
+        // These are AUTOMATIC discounts — they apply at checkout with no code to
+        // type — so the title is all a buyer gets. Some merchants write that title
+        // for shoppers ("Buy 2 get 5% OFF"); this one named them for the back
+        // office: Student, ELSPETBF2024, DL230. Thirteen of those stacked above
+        // the products, saying nothing and offering nothing to do.
+        //
+        // A percentage, a minimum quantity or an end date makes it an offer. A
+        // bare internal label does not, whatever it is called.
+        .filter((d) => d.percentOff !== undefined || d.minQuantity !== undefined || d.endsAt);
+    return {
+        ...(promotions.length ? { promotions } : {}),
+        ...(snap.discountsBlocked ? { promotionsBlocked: snap.discountsBlocked } : {}),
+    };
+};
+const money = (minor, currency) => {
+    const d = currency === 'JPY' || currency === 'KRW' ? 0 : 2;
+    return `${(minor / 10 ** d).toFixed(d)} ${currency}`;
+};
+// What a lens looks like in one line — the shape the demo conversation used:
+// name | replacement cycle | price | colours | rating.
+const optionValues = (p, nameLike) => p.options.find((o) => nameLike.test(o.name))?.values ?? [];
+// Prescription-ish option names, matched loosely: this store calls them `Left`,
+// `Right` and `Diopter`, and the next one will call them something else again.
+const POWER = /度数|prescription|power|diopter|sph|left|right/i;
+// Whether a product is a PAIR or a single lens, which decides how many
+// prescriptions the buyer has to give. Moody encodes it two ways at once — a
+// `-L`/`-R` suffix on the name, and one option instead of two — so read the
+// options (the structural fact) and use the name only to explain it.
+const eyeShape = (p) => {
+    const power = p.options.filter((o) => POWER.test(o.name));
+    if (power.length >= 2)
+        return 'pair';
+    if (power.length === 1)
+        return 'single';
+    return 'unknown';
+};
+/**
+ * An accessory names the thing it belongs to: "Rake FOR ELS PET Spaceship",
+ * "Liners for litter tray", "Replaceable Accessories". A shopper opening a
+ * storefront wants the litter box before the sponge strip that fits it.
+ *
+ * A heuristic on the TITLE, because the structured fields cannot answer it —
+ * this shop files all 30 products as "pet supplies". Checked against the real
+ * catalogue before it went in: 11 main products, 19 accessories, split where a
+ * person would split them.
+ */
+const ACCESSORY = /\bfor\b|\baccessor|\bliner|\brefill|\bspare\b|\breplacement\b|\breplaceable\b/i;
+export const isAccessory = (title) => ACCESSORY.test(title);
+const productSummary = (p, imageProxy) => ({
+    name: p.title,
+    handle: p.handle,
+    // The lens's page on Moody's own site — reviews, the size guide, the photos
+    // we do not carry. A buyer who wants to read more should land there, not on a
+    // *.myshopify.com address they have never heard of.
+    url: p.url,
+    price: p.fromPriceMinor !== undefined ? money(p.fromPriceMinor, p.currency) : undefined,
+    // What the buyer must still choose, in the store's own words. Not "colours":
+    // at Moody the colour is the product name, and inventing a colour axis that
+    // does not exist would have the assistant asking an unanswerable question.
+    choices: p.options.map((o) => ({ name: o.name, count: o.values.length })),
+    // Present ONLY when the store actually has a prescription axis.
+    //
+    // These are derived from the option names, so a shop that sells litter boxes
+    // got `eyes: 'unknown'` and `prescriptions: []` on every product — which does
+    // not read as "not applicable", it reads as "this store has prescriptions and
+    // I could not find them", and invites the assistant to ask a buyer for a
+    // diopter they do not have. Absent says what empty could not.
+    ...(() => {
+        const power = p.options.filter((o) => POWER.test(o.name));
+        return power.length ? { eyes: eyeShape(p), prescriptions: power[0]?.values ?? [] } : {};
+    })(),
+    type: p.productType || undefined,
+    tags: p.tags,
+    image: p.imageUrl && imageProxy ? `${imageProxy}${encodeURIComponent(p.imageUrl)}` : p.imageUrl,
+    // The direct CDN url, for a host whose CSP allows it (and for a reader that
+    // wants the real address rather than our proxy's).
+    imageCdn: p.imageUrl,
+});
+const notLoaded = (deps) => {
+    if (deps.catalog.list().length > 0)
+        return null;
+    const err = deps.catalog.current.lastError;
+    return {
+        structured: { view: 'error', error: 'catalog-unavailable', detail: err ?? null },
+        text: `The ${deps.merchantName} catalog is not loaded yet${err ? ` (${err})` : ''}. Try again in a moment.`,
+    };
+};
+export const callTool = async (deps, name, args) => {
+    if (name === deps.tools.list) {
+        const blocked = notLoaded(deps);
+        if (blocked)
+            return blocked;
+        const q = String(args.query ?? '')
+            .trim()
+            .toLowerCase();
+        const maxPrice = typeof args.maxPrice === 'number' ? args.maxPrice : undefined;
+        const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(args.limit, 50) : 20;
+        let items = deps.catalog.list();
+        // Widened, and never empty when the shelf is not.
+        //
+        // The naive substring match answered "brown lenses" and "棕色系" with
+        // nothing, so the assistant tried again, and again, each attempt drawing its
+        // own card — the buyer watched three storefronts stack up in the transcript
+        // for one question. The store is 382 products; a search over it should
+        // return the near misses, not a wall.
+        let relaxedFrom;
+        if (q) {
+            const hay = (p) => [p.title, p.handle, p.productType, p.description, ...p.tags].join(' ').toLowerCase();
+            // WHERE the match landed decides the order, on BOTH paths below.
+            //
+            // The ranking used to exist only on the relaxed path — which is the one a
+            // single word almost never takes. "grey" IS a substring of several brown
+            // lenses' descriptions, so it matched exactly, skipped the ranking
+            // entirely, and led a search for grey with Oolong Brown and Barley Tea.
+            // The comment further down predicted this exact failure and the fix was
+            // applied to the wrong branch.
+            const nameFirst = (list, terms) => {
+                const inName = (p) => terms.some((t) => `${p.title} ${p.handle} ${p.tags.join(' ')}`.toLowerCase().includes(t));
+                return [...list.filter(inName), ...list.filter((p) => !inName(p))];
+            };
+            const exact = items.filter((p) => hay(p).includes(q));
+            if (exact.length > 0) {
+                items = nameFirst(exact, [q]);
+            }
+            else {
+                // Any word, then any colour word we can map. "Brown lenses" keeps
+                // "brown"; a Chinese colour term becomes the English one this store
+                // actually names its products with.
+                //
+                // Ranked by WHERE the match landed, because the colour is the product
+                // NAME here and the descriptions are full of other colours: "Matcha
+                // Green" says "hojicha-brown iris details", so an unranked search for
+                // brown puts a green lens in the buyer's first row.
+                // A single CJK character IS a word (灰 = grey), so the one-letter filter
+                // only applies to alphabetic ones, where it drops "a"/"of".
+                // Split on every separator a picker or a person actually types, the
+                // full-width ones included: "棕色系（自然）" arrives whole, and one
+                // unhandled bracket is the difference between a colour family and all
+                // 382 products.
+                const words = q
+                    .split(/[\s,，、;；:：/|·()（）[\]【】{}"'“”‘’]+/)
+                    .filter((w) => w.length > 1 || /[一-鿿]/.test(w));
+                const terms = [
+                    ...new Set([...words, ...words.flatMap((w) => COLOUR_WORDS[colourKey(w)] ?? [])]),
+                ];
+                const loose = terms.length
+                    ? items.filter((p) => terms.some((t) => hay(p).includes(t)))
+                    : [];
+                if (loose.length > 0) {
+                    items = nameFirst(loose, terms);
+                    relaxedFrom = q;
+                }
+                else {
+                    // Still nothing. Show the shelf rather than an empty card: the next
+                    // move is the buyer narrowing it, and they cannot narrow nothing.
+                    relaxedFrom = q;
+                }
+            }
+        }
+        if (maxPrice !== undefined) {
+            items = items.filter((p) => {
+                if (p.fromPriceMinor === undefined)
+                    return false;
+                const d = p.currency === 'JPY' || p.currency === 'KRW' ? 0 : 2;
+                return p.fromPriceMinor / 10 ** d <= maxPrice;
+            });
+        }
+        // Accessories after the things they attach to, and only when the buyer did
+        // not ask for something specific — a search for "liner" should still put
+        // liners first. Stable, so within each group the shop's own order survives.
+        const ranked = q
+            ? items
+            : [
+                ...items.filter((p) => !isAccessory(p.title)),
+                ...items.filter((p) => isAccessory(p.title)),
+            ];
+        const products = ranked.slice(0, limit).map((p) => productSummary(p, deps.imageProxy));
+        const lines = products.map((p) => `- **${p.name}**${p.price ? ` · ${p.price}` : ''}` +
+            `${p.eyes === 'pair' ? ' · pair (needs both eyes)' : p.eyes === 'single' ? ' · single lens' : ''}`);
+        return {
+            structured: {
+                view: 'products',
+                merchant: deps.merchantName,
+                ...(deps.logoUrl ? { logoUrl: deps.logoUrl } : {}),
+                toolNames: { get: deps.tools.get, checkout: deps.tools.checkout },
+                vocab: { noun: deps.vocab.noun, nounPlural: deps.vocab.nounPlural },
+                products,
+                total: items.length,
+                // The shop's live offers. They are attached to no product, so without
+                // this the card quotes a price the buyer beats at checkout and never
+                // mentions the deal that would have made them buy two.
+                ...promoPayload(deps),
+                // What the card offers as filter chips, computed from THESE results
+                // rather than a list we invented. The buyer narrows inside the card, so
+                // narrowing costs no tool call — and a tool call is what put three
+                // storefronts in the transcript for one question.
+                facets: facetsOf(products),
+                // Say when the answer is broader than what was asked, so the card can
+                // label it and the assistant does not read it as an exact match.
+                ...(relaxedFrom ? { relaxedFrom } : {}),
+            },
+            text: [
+                products.length
+                    ? `${products.length} of ${items.length} ${deps.vocab.nounPlural}:\n${lines.join('\n')}`
+                    : 'This store has no products loaded right now.',
+                // The offers, in one line. Shopify applies them at its own checkout
+                // whether or not anyone mentions them — but a buyer who does not know
+                // about "buy 2 get 5% off" buys one.
+                deps.catalog.current.discounts.length
+                    ? `Store offers right now: ${deps.catalog.current.discounts.map((d) => d.title).join(' · ')} (applied automatically at checkout).`
+                    : '',
+                // Tell the assistant it already has the near misses. Otherwise it reads
+                // a narrow result as a failure and searches again, and every retry draws
+                // another storefront card in front of the buyer.
+                relaxedFrom
+                    ? `(Nothing matched "${relaxedFrom}" exactly — these are the closest. Do NOT search again; ask the buyer to narrow it, or show these.)`
+                    : '',
+            ]
+                .filter(Boolean)
+                .join('\n'),
+        };
+    }
+    if (name === deps.tools.get) {
+        const blocked = notLoaded(deps);
+        if (blocked)
+            return blocked;
+        const p = deps.catalog.byHandleOrTitle(String(args.product ?? ''));
+        if (!p) {
+            return {
+                structured: { view: 'error', error: 'no-such-product' },
+                text: `No ${deps.vocab.noun} called "${String(args.product ?? '')}". Try ${deps.tools.list}.`,
+            };
+        }
+        // Variants are loaded HERE, for this one product — the catalogue holds none.
+        const variants = await deps.catalog.variantsFor(p.handle);
+        const inStock = variants.filter((v) => v.available);
+        return {
+            structured: {
+                view: 'product',
+                merchant: deps.merchantName,
+                ...(deps.logoUrl ? { logoUrl: deps.logoUrl } : {}),
+                toolNames: { get: deps.tools.get, checkout: deps.tools.checkout },
+                vocab: { noun: deps.vocab.noun, nounPlural: deps.vocab.nounPlural },
+                product: {
+                    ...productSummary(p, deps.imageProxy),
+                    description: p.description,
+                    images: p.images,
+                    currency: p.currency,
+                    options: p.options,
+                    // Capped in the payload: 676 rows is not a thing to put in a tool
+                    // result, and the options above are what the buyer chooses from.
+                    variantCount: variants.length,
+                    inStockCount: inStock.length,
+                    // WHICH combinations can actually be bought, as option maps:
+                    // [{Left:'-5.75', Right:'-5.50'}]. This is what the picker needs and
+                    // the option lists above cannot express — "Left -5.75 is offered" and
+                    // "Right -5.50 is offered" says nothing about whether that PAIR exists,
+                    // and at this store 674 of the 676 pairs do not. Without it the buyer
+                    // picks from 26×26 chips and is told "sold out" almost every time.
+                    //
+                    // Small in practice BECAUSE it is in-stock only: 2 rows for Matcha
+                    // Green, 26 for a fully stocked single. Capped anyway — a fully stocked
+                    // pair would be 676 rows in a tool result the model also reads — and
+                    // the flag tells the picker to stop filtering rather than filter on a
+                    // truncated list, which would hide buyable prescriptions.
+                    ...inStockCombos(variants),
+                    // In-stock FIRST. A pair is Left × Right in the merchant's own order,
+                    // so the first 30 rows are the whole 0.00 row and a slice of -1.00 —
+                    // and at this store those are sold out while the stocked ones sit deep
+                    // in the tail. Showing the first 30 answers "what can I buy?" with
+                    // thirty things you cannot, which is worse than showing none.
+                    variants: [...inStock, ...variants.filter((v) => !v.available)].slice(0, 30).map((v) => ({
+                        variantId: v.variantId,
+                        title: v.title,
+                        price: money(v.priceMinor, p.currency),
+                        wasPrice: v.compareAtMinor ? money(v.compareAtMinor, p.currency) : undefined,
+                        available: v.available,
+                        options: v.options,
+                    })),
+                },
+            },
+            text: [
+                `**${p.title}** — ${p.fromPriceMinor !== undefined ? money(p.fromPriceMinor, p.currency) : ''}`,
+                ...p.options.map((o) => `${o.name}: ${o.values.join(' / ')}`),
+                // Say it plainly. Every value above is offered; far fewer are stocked,
+                // and an assistant reading only the option lists will confidently name a
+                // prescription that cannot be bought.
+                inStock.length === 0
+                    ? `OUT OF STOCK: none of the ${variants.length} combinations is in stock right now.`
+                    : inStock.length < variants.length
+                        ? `In stock: ${inStock.length} of ${variants.length} combinations — the values listed above are what the store OFFERS, not what it has. Check with ${deps.tools.checkout} before promising one.`
+                        : '',
+                p.description,
+            ]
+                .filter(Boolean)
+                .join('\n'),
+        };
+    }
+    if (name === deps.tools.checkout) {
+        const blocked = notLoaded(deps);
+        if (blocked)
+            return blocked;
+        const p = deps.catalog.byHandleOrTitle(String(args.product ?? ''));
+        if (!p) {
+            return {
+                structured: { view: 'error', error: 'no-such-product' },
+                text: `No ${deps.vocab.noun} called "${String(args.product ?? '')}".`,
+            };
+        }
+        const choices = {};
+        for (const [k, v] of Object.entries((args.options ?? {}))) {
+            if (typeof v === 'string' || typeof v === 'number')
+                choices[k] = String(v);
+        }
+        const variants = await deps.catalog.variantsFor(p.handle);
+        const variant = resolveVariant(variants, choices);
+        if (!variant) {
+            // Deliberately NOT a best guess. The options on a lens are the colour and
+            // the prescription; getting the second one wrong sends someone a lens they
+            // cannot wear, and a plausible guess is exactly how that happens.
+            //
+            // In the store's own words, and only what the store actually offers. Both
+            // readers below need that: the card pre-selects from it, and the prose has
+            // to call `-2.0` against a `-2.00` option ANSWERED — telling an assistant
+            // a question is still open when the buyer already answered it is how the
+            // buyer gets asked their prescription twice.
+            const given = snapChoices(p.options, choices);
+            return {
+                structured: {
+                    view: 'needs-options',
+                    merchant: deps.merchantName,
+                    ...(deps.logoUrl ? { logoUrl: deps.logoUrl } : {}),
+                    toolNames: { get: deps.tools.get, checkout: deps.tools.checkout },
+                    vocab: { noun: deps.vocab.noun, nounPlural: deps.vocab.nounPlural },
+                    product: productSummary(p, deps.imageProxy),
+                    options: p.options,
+                    eyes: eyeShape(p),
+                    given,
+                    // The picker opens on THIS payload when an assistant calls checkout
+                    // straight from the conversation, so it needs the same stock list the
+                    // product view gets — otherwise the buyer is offered 26x26 chips and
+                    // told "sold out" on almost every one of them.
+                    ...inStockCombos(variants),
+                },
+                text: `**${p.title}** needs ${p.options.length === 1 ? 'one choice' : `${p.options.length} choices`}${eyeShape(p) === 'pair' ? ' — it is a PAIR, so both eyes' : ''}:\n${p.options
+                    .map((o) => `- ${o.name}${given[o.name] ? ` (given: ${given[o.name]})` : ' ← still needed'}: ${o.values.join(' / ')}`)
+                    .join('\n')}\nAsk the buyer for what is missing. Never assume one answer carries to another option, and never round to a nearby value — the wrong one is something they cannot use.`,
+            };
+        }
+        if (!variant.available) {
+            return {
+                structured: {
+                    view: 'out-of-stock',
+                    product: productSummary(p, deps.imageProxy),
+                    variant: variant.title,
+                },
+                text: `**${p.title} — ${variant.title}** is out of stock right now.`,
+            };
+        }
+        // Bounded: a cart link is a public URL, and an unbounded quantity in one is
+        // a link that looks like this store sells 10,000 of something.
+        const quantity = typeof args.quantity === 'number' && args.quantity > 0
+            ? Math.min(Math.floor(args.quantity), 20)
+            : 1;
+        // Send them to the checkout on the SAME host as the product page they were
+        // just looking at, not to `<handle>.myshopify.com`. Taken from the product
+        // rather than from config because that is where the shop's own domain
+        // already is, and because the two links must not disagree: a card offering
+        // moodycosmetics.com/products/… and a Buy leading somewhere else reads as a
+        // swapped link, which is precisely what buyers are taught to distrust.
+        // Falls back to the myshopify host, which still works, when the storefront
+        // domain is unknown.
+        const storefrontDomain = p.url ? new URL(p.url).host : undefined;
+        const url = cartPermalink({ ...deps.shopify, ...(storefrontDomain ? { storefrontDomain } : {}) }, [{ variantId: variant.variantId, quantity }], {
+            attributes: {
+                Source: 'Curless',
+                ...(deps.assistant ? { Assistant: deps.assistant } : {}),
+            },
+        });
+        return {
+            structured: {
+                view: 'checkout',
+                merchant: deps.merchantName,
+                ...(deps.logoUrl ? { logoUrl: deps.logoUrl } : {}),
+                toolNames: { get: deps.tools.get, checkout: deps.tools.checkout },
+                vocab: { noun: deps.vocab.noun, nounPlural: deps.vocab.nounPlural },
+                product: productSummary(p, deps.imageProxy),
+                variant: {
+                    title: variant.title,
+                    options: variant.options,
+                    price: money(variant.priceMinor, p.currency),
+                },
+                quantity,
+                total: money(variant.priceMinor * quantity, p.currency),
+                checkoutUrl: url,
+            },
+            text: `**${p.title} — ${variant.title}** ×${quantity} · ${money(variant.priceMinor * quantity, p.currency)}\n\nPay on ${deps.merchantName}'s checkout: ${url}\n\n(Payment and the order itself happen on Moody's own Shopify checkout.)`,
+        };
+    }
+    if (name === deps.tools.lookupOrder) {
+        const res = await lookupShopifyOrder(deps.shopify, {
+            orderNumber: String(args.orderNumber ?? ''),
+            email: String(args.email ?? ''),
+        });
+        if (!res.found) {
+            // One answer for "no such order" and for "wrong email" — see the adapter.
+            return {
+                structured: { view: 'order-not-found' },
+                text: 'No order matches that order number and email. Check both against the confirmation email.',
+            };
+        }
+        const lines = res.lines
+            .map((l) => `- ${l.quantity}× ${l.title}${l.variantTitle ? ` (${l.variantTitle})` : ''}`)
+            .join('\n');
+        return {
+            structured: { view: 'order', merchant: deps.merchantName, order: res },
+            text: [
+                `**${res.name}** · ${money(res.totalMinor, res.currency)} · ${res.financialStatus}${res.fulfillmentStatus ? ` · ${res.fulfillmentStatus}` : ''}`,
+                lines,
+                res.trackingUrls.length ? `Tracking: ${res.trackingUrls.join(' ')}` : '',
+                res.statusUrl ? `Order status page: ${res.statusUrl}` : '',
+            ]
+                .filter(Boolean)
+                .join('\n'),
+        };
+    }
+    return { structured: { view: 'error', error: 'unknown-tool' }, text: `Unknown tool: ${name}` };
+};
+/**
+ * `productSummary` under test. Exported rather than reached through a live
+ * catalogue because the thing worth pinning is the SHAPE — which fields exist
+ * for which store — and a fetch mock would bury that behind plumbing.
+ */
+export const productSummaryForTest = (p, imageProxy) => productSummary(p, imageProxy);
+//# sourceMappingURL=tools.js.map