@binaryandthread/mcp 0.4.12 → 0.4.14

package/README.md

@@ -117,3 +117,8 @@ fits (regular and oversize, priced apart), `list_products` marks it (`fits`, `pr
 lists sizes and prices per fit (pass `fit` to narrow), and `add_to_cart` **requires** `fit` for it:
 without it the tool returns an error naming both fits, and nothing is added. Colours and sizes follow the ship-to region:
 `get_product` lists the ones you can buy where the cart ships.
+
+`add_to_cart` by `handle` also **requires** `size` whenever the colour comes in more than one: without it
+the tool returns the sizes and asks the agent to put the choice to the buyer, and nothing is added. A
+`variant_id` already names its size. `get_cart` and `add_to_cart` list each line's `size` and `colour`,
+and `get_cart` on a cart that was already checked out says so (`completed: true`) instead of listing it.

package/dist/bin.js

@@ -220,13 +220,19 @@ var StoreClient = class {
         } catch {
           parsed = {};
         }
-        if (opts.cartRecovery && (res.status === 404 || res.status === 409 || String(parsed.type ?? "").includes("cart.completed") || /cart.*complete/i.test(String(parsed.message ?? "")))) {
+        const idempotencyConflict = res.status === 409 && parsed.code === "IDEMPOTENCY_CONFLICT";
+        const parsedType = String(parsed.type ?? "");
+        if (opts.cartRecovery && (res.status === 404 || parsedType === "cart_completed" || parsedType.includes("cart.completed") || /cart.*complete/i.test(String(parsed.message ?? "")))) {
           throw new RecoverableCartError(
             `cart is stale or completed (HTTP ${res.status})`,
             res.status
           );
         }
-        if (res.status === 429) {
+        if (idempotencyConflict) {
+          retryAfterMs = parseRetryAfterMs(res);
+          lastErr = new StoreApiError(`request in flight (HTTP 409)`, 409, path);
+          this.logWarn("store.request.idempotency_conflict", { path, attempt: attempt + 1, retryAfterMs });
+        } else if (res.status === 429) {
           retryAfterMs = parseRetryAfterMs(res);
           lastErr = new StoreApiError(`rate limited (HTTP 429)`, 429, path);
           this.logWarn("store.request.rate_limited", {
@@ -624,12 +630,20 @@ function supplierOf(p) {
   return v === "gelato" || v === "printful" ? v : null;
 }
 var PRINTFUL_BLANK_COLOURS = {
-  "ascolour-5082": ["black", "white", "coal", "eucalyptus", "bone", "grey", "khaki", "indigo"]
+  "ascolour-5082": ["black", "white", "coal", "eucalyptus", "bone", "grey", "khaki", "indigo"],
   // TB124, TB126
+  "bellacanvas-4711": ["asphalt", "dust", "navy", "maroon", "forest", "jet"]
+  // TB128: the sweatshirt; TB129: + jet (its Black)
 };
 var PRINTFUL_BLANK_SIZES = {
-  "ascolour-5082": ["s", "m", "l", "xl", "2xl"]
+  "ascolour-5082": ["s", "m", "l", "xl", "2xl"],
+  "bellacanvas-4711": ["s", "m", "l", "xl", "2xl"]
 };
+function printfulBlankOf(p) {
+  const v = (p.metadata ?? {})["bt_blank"];
+  if (v === void 0 || v === null) return "ascolour-5082";
+  return typeof v === "string" && Object.prototype.hasOwnProperty.call(PRINTFUL_BLANK_COLOURS, v) ? v : null;
+}
 var PRINTFUL_SERVED_COUNTRIES = [
   "se",
   "us",
@@ -660,29 +674,30 @@ var PRINTFUL_SERVED_COUNTRIES = [
   "si",
   "es"
 ];
-function printfulBlankFor(fit, countryCode) {
+function printfulBlankFor(fit, countryCode, productBlank = "ascolour-5082") {
   if (!PRINTFUL_SERVED_COUNTRIES.includes((countryCode ?? "").trim().toLowerCase())) return null;
-  return fit === "regular" ? "ascolour-5082" : null;
+  if (productBlank === null) return null;
+  return fit === "regular" ? productBlank : null;
 }
 function sizeKey(size) {
   const s = size.trim().toLowerCase();
   return s === "xxl" ? "2xl" : s === "xxxl" ? "3xl" : s;
 }
-function blankRule(fit, countryCode, supplier) {
+function blankRule(fit, countryCode, supplier, productBlank) {
   if (supplier === null) return null;
   if (supplier === "printful") {
-    const pb = printfulBlankFor(fit, countryCode);
+    const pb = printfulBlankFor(fit, countryCode, productBlank);
     return pb ? { colours: PRINTFUL_BLANK_COLOURS[pb], sizes: PRINTFUL_BLANK_SIZES[pb] } : null;
   }
   const blank = blankFor(fit, countryCode);
   return blank ? { colours: BLANK_COLOURS[blank], sizes: BLANK_SIZES[blank] } : null;
 }
-function colourBuyable(fit, colour, countryCode, supplier = "gelato") {
-  const rule = blankRule(fit, countryCode, supplier);
+function colourBuyable(fit, colour, countryCode, supplier = "gelato", printfulBlank = "ascolour-5082") {
+  const rule = blankRule(fit, countryCode, supplier, printfulBlank);
   return !!rule && rule.colours.includes(colour.trim().toLowerCase());
 }
-function sizeBuyable(fit, size, countryCode, supplier = "gelato") {
-  const rule = blankRule(fit, countryCode, supplier);
+function sizeBuyable(fit, size, countryCode, supplier = "gelato", printfulBlank = "ascolour-5082") {
+  const rule = blankRule(fit, countryCode, supplier, printfulBlank);
   return !!rule && rule.sizes.includes(sizeKey(size));
 }
 function legacyFit(p) {
@@ -701,11 +716,12 @@ function variantsOfFit(p, fit) {
 function coloursFor(p, fit, countryCode) {
   const gate = gateFit(p, fit);
   const supplier = supplierOf(p);
+  const pb = printfulBlankOf(p);
   const out = [];
   for (const v of variantsOfFit(p, fit)) {
     const c = variantColour(v);
     if (!c || out.includes(c)) continue;
-    if (gate && countryCode !== void 0 && !colourBuyable(gate, c, countryCode, supplier)) continue;
+    if (gate && countryCode !== void 0 && !colourBuyable(gate, c, countryCode, supplier, pb)) continue;
     out.push(c);
   }
   return out;
@@ -713,13 +729,14 @@ function coloursFor(p, fit, countryCode) {
 function sizesFor(p, fit, colour, countryCode) {
   const gate = gateFit(p, fit);
   const supplier = supplierOf(p);
+  const pb = printfulBlankOf(p);
   const target = colour.trim().toLowerCase();
   const out = [];
   for (const v of variantsOfFit(p, fit)) {
     if (variantColour(v) !== target) continue;
     const s = sizeOfVariant(v);
     if (!s || out.includes(s)) continue;
-    if (gate && countryCode !== void 0 && !sizeBuyable(gate, s, countryCode, supplier)) continue;
+    if (gate && countryCode !== void 0 && !sizeBuyable(gate, s, countryCode, supplier, pb)) continue;
     out.push(s);
   }
   return out;
@@ -758,21 +775,22 @@ function resolveVariant(p, opts) {
   const pool = variantsOfFit(p, fit);
   const gate = gateFit(p, fit);
   const supplier = supplierOf(p);
+  const pb = printfulBlankOf(p);
   const colours = coloursFor(p, fit, opts.countryCode);
-  const colour = colourKey(opts.colour ?? "") || (colours[0] ?? null);
-  if (gate && colour && opts.countryCode !== void 0 && !colourBuyable(gate, colour, opts.countryCode, supplier)) {
+  const colour = colourKey(opts.colour ?? "", productColours(p)) || (colours[0] ?? null);
+  if (gate && colour && opts.countryCode !== void 0 && !colourBuyable(gate, colour, opts.countryCode, supplier, pb)) {
     return { ok: false, reason: "fit_unavailable", fit: gate, colour };
   }
   const size = (opts.size ?? "").trim() || null;
   const sizeLc = size?.toLowerCase();
   const buyableSizes = colour ? sizesFor(p, fit, colour, opts.countryCode) : [];
   const sizeExists = !!size && pool.some((x) => (sizeOfVariant(x) ?? x.title ?? "").toLowerCase() === size.toLowerCase());
-  if (gate && size && sizeExists && opts.countryCode !== void 0 && !sizeBuyable(gate, size, opts.countryCode, supplier)) {
+  if (gate && size && sizeExists && opts.countryCode !== void 0 && !sizeBuyable(gate, size, opts.countryCode, supplier, pb)) {
     return { ok: false, reason: "size_unavailable", fit: gate, size, sizes: buyableSizes };
   }
   const sellable = gate && opts.countryCode !== void 0 ? pool.filter((x) => {
     const s = sizeOfVariant(x);
-    return !s || sizeBuyable(gate, s, opts.countryCode, supplier);
+    return !s || sizeBuyable(gate, s, opts.countryCode, supplier, pb);
   }) : pool;
   const v = sellable.find((x) => {
     const colourOk = !colour || variantColour(x) === colour;
@@ -797,15 +815,22 @@ var COLOUR_LABELS = {
   bone: "Faded Bone",
   grey: "Faded Grey",
   khaki: "Faded Khaki",
-  indigo: "Faded Indigo"
+  indigo: "Faded Indigo",
+  jet: "Black"
 };
 function colourLabel(colour) {
   const c = colour.trim();
   if (!c) return c;
   return COLOUR_LABELS[c.toLowerCase()] ?? c.charAt(0).toUpperCase() + c.slice(1).toLowerCase();
 }
-function colourKey(colour) {
+function colourKey(colour, available) {
   const c = colour.trim().toLowerCase();
+  if (available) {
+    const keys = available.map((k) => k.trim().toLowerCase());
+    if (keys.includes(c)) return c;
+    return keys.find((k) => colourLabel(k).toLowerCase() === c) ?? c;
+  }
+  if (Object.prototype.hasOwnProperty.call(COLOUR_LABELS, c)) return c;
   const key = Object.entries(COLOUR_LABELS).find(([, label]) => label.toLowerCase() === c)?.[0];
   return key ?? c;
 }
@@ -921,6 +946,31 @@ function firstImageUrl(images) {
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+function sizeTokenOf(title) {
+  return titleSegments(title).find((s) => SIZE_TOKEN.test(s)) ?? null;
+}
+var SIZE_ORDER = ["xxs", "xs", "s", "m", "l", "xl", "2xl", "xxl", "3xl", "xxxl", "4xl", "5xl"];
+function sortSizes(sizes) {
+  const rank = (s) => {
+    const i = SIZE_ORDER.indexOf(s.trim().toLowerCase());
+    return i === -1 ? SIZE_ORDER.length : i;
+  };
+  return [...sizes].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+}
+function lineOption(item, titles) {
+  const o = item.variant?.options?.find((x) => titles.includes((x.option?.title ?? "").toLowerCase()));
+  const v = typeof o?.value === "string" ? o.value.trim() : "";
+  return v ? v : null;
+}
+function lineColour(item) {
+  const opt = lineOption(item, ["colour", "color"]);
+  if (opt) return opt.toLowerCase();
+  const vt = (item.variant_title ?? "").toString();
+  return vt ? variantColour({ id: "x", title: vt }) : null;
+}
+function lineSize(item) {
+  return lineOption(item, ["size"]) ?? sizeTokenOf(item.variant_title);
+}
 function orderStage(o) {
   const status = (o.status ?? "").trim().toLowerCase();
   if (status === "canceled" || status === "refunded") return "reverted";
@@ -1057,7 +1107,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/version.ts
-var VERSION = "0.4.12";
+var VERSION = "0.4.14";
 
 // src/onboarding.ts
 var GETTING_STARTED_URI = "bt://getting-started";
@@ -1275,12 +1325,18 @@ function taxSuffix(isTaxInclusive) {
   return isTaxInclusive ? " incl. VAT" : "";
 }
 function cartItems(cart) {
-  return (cart.items ?? []).map((li) => ({
-    variant_id: li.variant_id ?? null,
-    title: sanitize(li.product_title ?? li.title ?? "item", 80),
-    qty: li.quantity ?? 1,
-    total: li.total ?? null
-  }));
+  return (cart.items ?? []).map((li) => {
+    const size = lineSize(li);
+    const colour = lineColour(li);
+    return {
+      variant_id: li.variant_id ?? null,
+      title: sanitize(li.product_title ?? li.title ?? "item", 80),
+      size: size ? sanitize(size, 20) : null,
+      colour: colour ? sanitize(colour, 20) : null,
+      qty: li.quantity ?? 1,
+      total: li.total ?? null
+    };
+  });
 }
 function cartSummary(cart, region) {
   const lines = [];
@@ -1291,7 +1347,11 @@ function cartSummary(cart, region) {
   } else {
     for (const li of items) {
       const title = sanitize(li.product_title ?? li.title ?? "item", 80);
-      lines.push(`  ${li.quantity}x ${title} \u2014 ${fmtPrice(li.total, cart.currency_code ?? region?.currency_code)}`);
+      const rawColour = lineColour(li);
+      const colour = rawColour ? colourLabel(rawColour) : null;
+      const size = lineSize(li);
+      const tags = [colour, size].filter((x) => !!x).map((x) => ` \xB7 ${sanitize(x, 20)}`).join("");
+      lines.push(`  ${li.quantity}x ${title}${tags} \u2014 ${fmtPrice(li.total, cart.currency_code ?? region?.currency_code)}`);
     }
   }
   const cur = cart.currency_code ?? region?.currency_code;
@@ -1459,7 +1519,10 @@ function makeTools(client, opts = {}) {
           // the map used to hand out ids for colours the ship-to blank can't print, with the caveat buried
           // in a separate unavailable_colours field. Same derived answer, on the row an agent actually uses.
           // CAT-37 added the SIZE half — the US and EU oversize blanks have different size ranges.
-          buyable: (!gFit || !vColour || colourBuyable(gFit, vColour, shipCC, supplierOf(product))) && (!gFit || !vSize || sizeBuyable(gFit, vSize, shipCC, supplierOf(product)))
+          buyable: (
+            // TB129 review: judged by the product's OWN garment (a 4711 is not a 5082).
+            (!gFit || !vColour || colourBuyable(gFit, vColour, shipCC, supplierOf(product), printfulBlankOf(product))) && (!gFit || !vSize || sizeBuyable(gFit, vSize, shipCC, supplierOf(product), printfulBlankOf(product)))
+          )
         };
       });
       const sizeList = colours.length > 0 ? Object.fromEntries(colours.map((c) => [c, sizesForColour(product, c)])) : (product.variants ?? []).map((v) => v.title ?? "?");
@@ -1498,12 +1561,12 @@ function makeTools(client, opts = {}) {
   };
   const add_to_cart = {
     name: "add_to_cart",
-    description: "Add a piece to a cart. Pass cart_id to reuse an existing cart (the durable handle), or omit it to start a fresh one. Call get_product first to get valid sizes/colours (or an exact variant_id); for a design sold in two fits (regular / oversize, priced apart) you MUST pass `fit`. qty is capped at 20. Returns the cart_id and the server-side cart summary (VAT included where applicable). `region` (ISO-2) sets the ship-to country + currency of a NEW cart. A reused cart ships where it already ships: a `region` that disagrees with it is refused (start a new cart instead). If a reused cart has expired or was already checked out, a fresh one is made in the same region and the reply says cart_replaced: true.",
+    description: "Add a piece to a cart. Pass cart_id to reuse an existing cart (the durable handle), or omit it to start a fresh one. Call get_product first to get valid sizes/colours (or an exact variant_id); for a design sold in two fits (regular / oversize, priced apart) you MUST pass `fit`. size is required when the colour comes in more than one size: ask the buyer, never choose one for them. qty is capped at 20. Returns the cart_id and the server-side cart summary (VAT included where applicable). `region` (ISO-2) sets the ship-to country + currency of a NEW cart. A reused cart ships where it already ships: a `region` that disagrees with it is refused (start a new cart instead). If a reused cart has expired or was already checked out, a fresh one is made in the same region and the reply says cart_replaced: true.",
     inputSchema: {
       handle: z.string().optional().describe("product handle (resolves a variant by size + colour; call get_product for valid values)"),
       variant_id: z.string().optional().describe("a specific variant id from get_product (overrides handle/size/colour)"),
       fit: z.string().optional().describe("regular or oversize; REQUIRED when the design comes in both (get_product lists them)"),
-      size: z.string().optional().describe("size label from get_product (it lists the sizes you can buy where the cart ships)"),
+      size: z.string().optional().describe("size label from get_product (it lists the sizes you can buy where the cart ships); required when the colour comes in more than one size, ask the buyer"),
       colour: z.string().optional().describe("piece colour from get_product, e.g. black / white, or the name shown, e.g. Faded Black (default: the first colour you can buy where the cart ships)"),
       qty: z.number().int().positive().max(20).optional().describe("quantity, 1\u201320 (default 1)"),
       cart_id: z.string().optional().describe("reuse this cart; omit to create a new one"),
@@ -1519,6 +1582,7 @@ function makeTools(client, opts = {}) {
         } catch (e) {
           if (!(e instanceof RecoverableCartError)) throw e;
         }
+        if (existing?.completed_at) existing = null;
       }
       let region;
       let shipCC;
@@ -1557,12 +1621,13 @@ function makeTools(client, opts = {}) {
         const gFit = gateFit(owner, variantFit(v));
         const shipCC2 = shipCC;
         const supplier = supplierOf(owner);
-        if (gFit && vColour && !colourBuyable(gFit, vColour, shipCC2, supplier)) {
+        const blank = printfulBlankOf(owner);
+        if (gFit && vColour && !colourBuyable(gFit, vColour, shipCC2, supplier, blank)) {
           return errorText(
             `${sanitize(colourLabel(vColour), 20)} is not available in ${gFit} for ${sanitize(shipCC2 ?? "this region", 8)}. nothing was added.`
           );
         }
-        if (gFit && vSize && !sizeBuyable(gFit, vSize, shipCC2, supplier)) {
+        if (gFit && vSize && !sizeBuyable(gFit, vSize, shipCC2, supplier, blank)) {
           return errorText(
             `size ${sanitize(vSize, 20)} is not made in ${gFit} for ${sanitize(shipCC2 ?? "this region", 8)}. nothing was added.`
           );
@@ -1596,6 +1661,13 @@ function makeTools(client, opts = {}) {
               `"${sanitize(handle, 60)}" isn't sold in fit "${sanitize(r.requested, 20)}"${r.fits.length ? ` \u2014 it comes in ${r.fits.join(" / ")}` : ""}. nothing was added.`
             );
           }
+          const colourAsked = "colour" in r ? r.colour : null;
+          const madeIn = coloursFor(product, productFits(product).length > 0 ? r.fit ?? null : null);
+          if (colourAsked && (r.reason === "fit_unavailable" || r.reason === "not_found") && !madeIn.includes(colourAsked)) {
+            return errorText(
+              `"${sanitize(handle, 60)}" isn't made in ${sanitize(colourAsked, 20)}. colours: ${madeIn.map((c) => sanitize(c, 20)).join(" \xB7 ")} (pass one as colour). nothing was added.`
+            );
+          }
           if (r.reason === "fit_unavailable") {
             return errorText(
               `${sanitize(colourLabel(r.colour ?? ""), 20)} is not available in ${r.fit} for ${sanitize(shipCC ?? "this region", 8)}. nothing was added.`
@@ -1606,12 +1678,27 @@ function makeTools(client, opts = {}) {
               `size ${sanitize(r.size, 20)} is not made in ${r.fit} for ${sanitize(shipCC ?? "this region", 8)}${r.sizes.length ? ` \u2014 sizes here: ${r.sizes.map((x) => sanitize(x, 20)).join(" ")}` : ""}. nothing was added.`
             );
           }
+          if (size && r.colour && r.sizes.length) {
+            return errorText(
+              `"${sanitize(handle, 60)}" doesn't come in size ${sanitize(size, 20)} in ${sanitize(r.colour, 20)}. sizes: ${sortSizes(r.sizes).map((x) => sanitize(x, 20)).join(" ")}. nothing was added.`
+            );
+          }
           const have = r.colours.length ? ` available colours: ${r.colours.map((c) => sanitize(colourLabel(c), 20)).join(", ")}.` : "";
           const haveSizes = r.sizes.length ? ` sizes: ${r.sizes.map((x) => sanitize(x, 20)).join(" ")}.` : "";
           return errorText(
             `no variant for "${sanitize(handle, 60)}"${r.fit ? ` fit ${r.fit}` : ""}${size ? ` size ${sanitize(size, 20)}` : ""}${r.colour ? ` (${sanitize(colourLabel(r.colour), 20)})` : ""}.${have}${haveSizes}`
           );
         }
+        if (!size?.trim()) {
+          const sizes = sortSizes(
+            r.colour ? sizesFor(product, r.fit, r.colour, shipCC) : [...new Set((product.variants ?? []).map((v) => sizeOfVariant(v)).filter((s) => !!s))]
+          );
+          if (sizes.length > 1) {
+            return errorText(
+              `size required for "${sanitize(handle, 60)}": ${sizes.map((x) => sanitize(x, 20)).join(" ")}${r.colour ? ` in ${sanitize(r.colour, 20)}` : ""}. ask the buyer which size, don't choose for them, then pass size. nothing was added.`
+            );
+          }
+        }
         variantId = r.variant.id;
       }
       const addTo = async (cartId) => client.addLineItem(cartId, variantId, qty);
@@ -1658,6 +1745,14 @@ ${cartSummary(cart, region)}`,
       const region = await client.resolveRegion(regionCC);
       try {
         const cart = await client.getCart(cartId);
+        if (cart.completed_at) {
+          return {
+            ...errorText(
+              "that cart was already checked out and became an order, so it cannot be edited. omit cart_id on the next add_to_cart to start a new one."
+            ),
+            structuredContent: { completed: true }
+          };
+        }
         const itemCount = (cart.items ?? []).reduce((n, li) => n + (li.quantity ?? 1), 0);
         return result(cartSummary(cart, region), {
           cart_id: cart.id,
@@ -1695,12 +1790,28 @@ ${cartSummary(cart, region)}`,
         }
         return errorText("couldn't attach a shipping method to this cart \u2014 checkout isn't available for it right now.");
       }
-      const mint = await client.mintCheckout(cartId, email, "mcp");
+      const completedAnswer = () => ({
+        ...errorText(
+          "that cart was already checked out and became an order. call check_payment with its session_id, or omit cart_id on add_to_cart to start a new one."
+        ),
+        structuredContent: { completed: true }
+      });
+      if (shipped.completed_at) {
+        return completedAnswer();
+      }
+      let mint;
+      try {
+        mint = await client.mintCheckout(cartId, email, "mcp");
+      } catch (e) {
+        if (e instanceof StoreApiError && e.status === 409) {
+          return completedAnswer();
+        }
+        throw e;
+      }
       const { checkout_url, session_id } = mint;
       const finalTotal = mint.total ?? shipped.total ?? null;
       const finalCurrency = mint.currency ?? shipped.currency_code ?? null;
       const totalStr = `${fmtPrice(finalTotal, finalCurrency)}${taxSuffix(isCartTaxInclusive(shipped))}`;
-      const discountLine = mint.discount && mint.discount.amount > 0 ? [`  dev channel: \u2212${fmtPrice(mint.discount.amount, finalCurrency)} (${mint.discount.pct}% off \u2014 for buying from the terminal/agent)`] : [];
       const moneyLines = cartMoneyRows({
         itemTotal: shipped.item_total,
         discountTotal: mint.discount?.amount,